@copado/agentia-cli 0.112.0-alpha.0 → 0.113.0-alpha.0

package/dist/lib/testing-operations.js

@@ -1,24 +1,37 @@
 /* eslint-disable no-await-in-loop, unicorn/text-encoding-identifier-case -- CRT polling waits between API checks and file operation payloads require the literal utf-8 enum. */
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import * as http from 'node:http';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import * as https from 'node:https';
 import { dirname, join, relative, resolve, sep } from 'node:path';
+import { inflateRawSync } from 'node:zlib';
 import { createTransactionId, CRT_GATEWAY_EVENT_SERVICE, gatewayRefererHeaders, getGatewayTransactionId, scheduleGatewayEventLog, } from './cicd-gateway.js';
-import { resolveTestingCredentials } from './testing-config.js';
-import { TESTING_DEFAULT_TIMEOUT_MS, TestingGateway } from './testing-gateway.js';
-import { createDefaultRobotSnapshotBase64, listSnapshotZipEntries, normalizeDownloadedFiles, normalizeTestingArray, normalizeTestingId, normalizeTestingRecord, redactTestingVariables, testingBuildAbortEndpoint, testingBuildLogsEndpoint, testingJobBuildsEndpoint, testingJobEndpoint, testingJobFilesDownloadEndpoint, testingJobFilesEndpoint, testingJobFilesUploadEndpoint, testingJobsEndpoint, testingProjectBuildsEndpoint, testingProjectDeleteEndpoint, testingProjectsEndpoint, testingRobotEndpoint, testingRobotJobsEndpoint, testingRobotsEndpoint, testingVariableEndpoint, testingVariablesEndpoint, } from './testing-types.js';
+import { paceBaseUrl, resolveTestingCredentials } from './testing-config.js';
+import { formatTestingDatasetKey, parseTestingDataTableRunSpecs, } from './testing-data-core.js';
+import { createTestingDataSession, getTestingDataTable, } from './testing-data-operations.js';
+import { TESTING_DEFAULT_TIMEOUT_MS, TESTING_MAX_RESPONSE_BYTES, TestingGateway, } from './testing-gateway.js';
+import { sanitizeTestingOutput, sanitizeTestingText, sanitizeTestingUrl } from './testing-sanitization.js';
+import { appendTestingQuery, createDefaultRobotSnapshotBase64, listSnapshotZipEntries, normalizeDownloadedFiles, normalizeTestingArray, normalizeTestingEnvelopeRecord, normalizeTestingId, normalizeTestingRecord, redactTestingVariables, testingBuildAbortEndpoint, testingBuildEndpoint, testingBuildLogsEndpoint, testingJobBuildsEndpoint, testingJobEndpoint, testingJobFilesDownloadEndpoint, testingJobFilesEndpoint, testingJobFilesUploadEndpoint, testingJobRefsEndpoint, testingJobsEndpoint, testingMetricsSearchEndpoint, testingPermissionEndpoint, testingPermissionsEndpoint, testingProjectBuildsEndpoint, testingProjectDeleteEndpoint, testingProjectEndpoint, testingProjectPermissionsEndpoint, testingProjectsEndpoint, testingRobotEndpoint, testingRobotJobsEndpoint, testingRobotsEndpoint, testingUserParameterEndpoint, testingUserParametersEndpoint, testingVariableEndpoint, testingVariablesEndpoint, } from './testing-types.js';
 export const DEFAULT_TESTING_AUTHOR = {
     email: 'agentia@copado.com',
     name: 'Agentia CLI',
 };
-const TESTING_TERMINAL_BUILD_STATUSES = new Set(['aborted', 'failed', 'finished', 'succeeded']);
+const TESTING_TERMINAL_BUILD_STATUSES = new Set([
+    'aborted',
+    'error',
+    'failed',
+    'finished',
+    'invalidxml',
+    'passed',
+    'succeeded',
+    'timeout',
+]);
 const TESTING_WAIT_INITIAL_INTERVAL_MS = 2000;
 const TESTING_WAIT_MAX_INTERVAL_MS = 10_000;
 const TESTING_WAIT_TIMEOUT_MS = 30 * 60_000;
-async function defaultTestingSnapshotFetch(url, headers, timeoutMs) {
-    const transport = url.protocol === 'http:' ? http : https;
+const TESTING_SECRET_VALUE_MAX_BYTES = 1024 * 1024;
+const TESTING_UPLOAD_VALUE_MAX_BYTES = 10 * 1024 * 1024;
+async function defaultTestingSnapshotFetch(url, headers, timeoutMs, maxResponseBytes) {
     return new Promise((resolvePromise, reject) => {
-        const req = transport.request({
+        const req = https.request({
             headers,
             hostname: url.hostname,
             method: 'GET',
@@ -27,11 +40,19 @@ async function defaultTestingSnapshotFetch(url, headers, timeoutMs) {
             timeout: timeoutMs,
         }, (response) => {
             const chunks = [];
-            response.on('data', (chunk) => chunks.push(chunk));
+            let responseBytes = 0;
+            response.on('data', (chunk) => {
+                responseBytes += chunk.length;
+                if (responseBytes > maxResponseBytes) {
+                    req.destroy(new Error(`CRT snapshot response exceeded the ${maxResponseBytes} byte safety limit.`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
             response.on('end', () => {
                 const status = response.statusCode ?? 0;
                 if (status >= 400) {
-                    reject(new Error(`CRT snapshot request failed (${status}). Request: GET ${url.toString()}`));
+                    reject(new Error(`CRT snapshot request failed (${status}). Request: GET ${sanitizeTestingUrl(url)}`));
                     return;
                 }
                 resolvePromise(Buffer.concat(chunks));
@@ -49,23 +70,58 @@ export async function listTestingProjects(options = {}) {
     const credentials = resolveOptions(options);
     const response = await TestingGateway.call({ endpoint: testingProjectsEndpoint(credentials.orgId), method: 'GET', service: 'platform' }, options);
     const projects = normalizeTestingArray(response);
-    return filterByName(projects, options.name, false);
+    return sanitizeTestingOutput(filterByName(projects, options.name, false));
 }
 export async function createTestingProject(options) {
+    requireNonBlank(options.name, 'CRT project name');
     const credentials = resolveOptions(options);
-    const body = {
-        description: options.description ?? '',
+    const body = omitUndefined({
+        dashboardId: options.dashboardId,
+        description: options.description,
         name: options.name,
-        projectType: 'ta',
-    };
+        projectExecutor: options.projectExecutor,
+        projectType: options.projectType ?? 'ta',
+    });
     const response = await TestingGateway.call({ body, endpoint: testingProjectsEndpoint(credentials.orgId), method: 'POST', service: 'platform' }, options);
-    return normalizeTestingRecord(response);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
 }
 export async function getTestingProject(options) {
-    return findTestingRecord(await listTestingProjects(options), options.projectId, 'project');
+    const response = await TestingGateway.call({ endpoint: testingProjectEndpoint(options.projectId), method: 'GET', service: 'platform' }, options);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
+}
+export async function updateTestingProject(options) {
+    const body = omitUndefined({ description: options.description, name: options.name });
+    requireBodyFields(body, 'Provide at least one project field to update.');
+    if (options.name !== undefined)
+        requireNonBlank(options.name, 'CRT project name');
+    const response = await TestingGateway.call({ body, endpoint: testingProjectEndpoint(options.projectId), method: 'PATCH', service: 'platform' }, options);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
+}
+export async function listTestingProjectPermissions(options) {
+    const response = await TestingGateway.call({ endpoint: testingProjectPermissionsEndpoint(options.projectId), method: 'GET', service: 'platform' }, options);
+    return sanitizeTestingOutput(normalizeTestingArray(response));
+}
+export async function getTestingProjectPermission(options) {
+    const response = await TestingGateway.call({ endpoint: testingPermissionsEndpoint(options.projectId), method: 'GET', service: 'platform' }, options);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
+}
+export async function setTestingProjectPermission(options) {
+    validateTestingPermissionRequest(options);
+    const body = [omitUndefined({
+            edit: options.edit,
+            groupId: options.groupId,
+            userId: options.userId,
+            view: options.view,
+        })];
+    const response = await TestingGateway.call({ body, endpoint: testingPermissionsEndpoint(options.projectId), method: 'POST', service: 'platform' }, options);
+    return sanitizeTestingOutput(normalizeTestingArray(response));
+}
+export async function deleteTestingProjectPermission(options) {
+    await TestingGateway.call({ endpoint: testingPermissionEndpoint(options.permissionId), method: 'DELETE', service: 'platform' }, options);
+    return { deleted: true, permissionId: options.permissionId };
 }
 export async function deleteTestingProject(options) {
-    await TestingGateway.call({ endpoint: testingProjectDeleteEndpoint(options.projectId), method: 'DELETE', service: 'pace' }, options);
+    await TestingGateway.call({ endpoint: testingProjectDeleteEndpoint(options.projectId), method: 'DELETE', service: 'platform' }, options);
     return { deleted: true, projectId: options.projectId };
 }
 export async function listTestingRobots(options) {
@@ -73,19 +129,47 @@ export async function listTestingRobots(options) {
     return normalizeTestingArray(response);
 }
 export async function createTestingRobot(options) {
-    const body = {
+    requireNonBlank(options.name, 'CRT robot name');
+    const body = omitUndefined({
         description: options.description ?? '',
-        fwVersion: options.fwVersion ?? 'stable',
+        fwVersion: options.fwVersion,
+        label: options.label,
         name: options.name,
-        os: options.os ?? 'linux',
-        robotType: options.robotType ?? 'default',
-        runEnvironment: options.kind === 'QConnect' ? 'paceconnect' : 'cloud',
-    };
+        os: options.os,
+        reporting: options.reporting,
+        robotType: options.robotType,
+        runEnvironment: options.kind === 'QConnect' ? 'paceconnect' : (options.kind ?? 'cloud'),
+    });
     const response = await TestingGateway.call({ body, endpoint: testingRobotsEndpoint(options.projectId), method: 'POST', service: 'pace' }, options);
-    return normalizeTestingRecord(response);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
 }
 export async function getTestingRobot(options) {
-    return findTestingRecord(await listTestingRobots(options), options.robotId, 'robot');
+    const response = await TestingGateway.call({ endpoint: testingRobotEndpoint(options.projectId, options.robotId), method: 'GET', service: 'pace' }, options);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
+}
+export async function updateTestingRobot(options) {
+    const updates = omitUndefined({
+        description: options.description,
+        fwVersion: options.fwVersion,
+        label: options.label,
+        name: options.name,
+        reporting: options.reporting,
+        robotType: options.robotType,
+    });
+    requireBodyFields(updates, 'Provide at least one robot field to update.');
+    if (options.name !== undefined)
+        requireNonBlank(options.name, 'CRT robot name');
+    const current = await getTestingRobot(options);
+    const body = omitUndefined({
+        description: options.description ?? stringField(current.description),
+        fwVersion: options.fwVersion ?? stringField(current.fwVersion),
+        label: options.label ?? stringField(current.label),
+        name: options.name ?? stringField(current.name),
+        reporting: options.reporting ?? stringField(current.reporting),
+        robotType: options.robotType ?? stringField(current.robotType),
+    });
+    const response = await TestingGateway.call({ body, endpoint: testingRobotEndpoint(options.projectId, options.robotId), method: 'PUT', service: 'pace' }, options);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
 }
 export async function deleteTestingRobot(options) {
     await TestingGateway.call({ endpoint: testingRobotEndpoint(options.projectId, options.robotId), method: 'DELETE', service: 'pace' }, options);
@@ -137,12 +221,44 @@ export function buildTestingGitStorageUpdate(options) {
 export async function createTestingJob(options) {
     const storage = buildTestingCreateJobStorage(options);
     const operations = storage.kind === 'git' || options.fileInput === undefined ? [] : buildFileAddOperations(options.fileInput);
-    const body = {
+    const body = omitUndefined({
+        analytics: options.analytics,
         description: options.description ?? '',
         domainCredentialId: storage.kind === 'git' ? options.gitDomainCredentialId : undefined,
         name: options.name,
+        parallelExecution: options.parallelExecution,
+        screen: options.screen,
+        showVideoParams: options.showVideoParams,
         storage,
-    };
+        suiteType: options.suiteType,
+        timeout: options.timeout,
+        validation: options.validation,
+    });
+    if (options.dryRun === true) {
+        return {
+            dryRun: true,
+            filesUploaded: operations.length,
+            job: sanitizeTestingOutput({
+                ...body,
+                storage: storage.kind === 'git'
+                    ? omitUndefined({
+                        branchOrTag: storage.branchOrTag,
+                        gitUrl: storage.gitUrl,
+                        gitUsername: storage.gitUsername,
+                        kind: storage.kind,
+                        useCallerCredentials: storage.useCallerCredentials,
+                    })
+                    : { kind: storage.kind },
+                upload: {
+                    author: options.uploadAuthor ?? DEFAULT_TESTING_AUTHOR,
+                    commitMessage: options.uploadCommitMessage,
+                    operations: sanitizeTestingFilePlan(operations),
+                    parentCommitHash: options.uploadParentCommitHash,
+                },
+            }),
+            projectId: options.projectId,
+        };
+    }
     const response = await TestingGateway.call({ body, endpoint: testingRobotJobsEndpoint(options.projectId, options.robotId), method: 'POST', service: 'pace' }, options);
     const job = normalizeTestingRecord(response);
     const jobId = normalizeTestingId(response);
@@ -155,8 +271,11 @@ export async function createTestingJob(options) {
     if (jobId !== undefined && operations.length > 0) {
         const upload = await uploadTestingJobFiles({
             ...options,
+            author: options.uploadAuthor,
+            commitMessage: options.uploadCommitMessage,
             jobId: numericId(jobId, 'job'),
             operations: [{ op: 'remove', path: 'tests.robot' }, ...operations],
+            parentCommitHash: options.uploadParentCommitHash,
             projectId: options.projectId,
         });
         result.filesUploaded = upload.operations.length - 1;
@@ -194,17 +313,56 @@ export async function listTestingJobFiles(options) {
     return listTestingSnapshotFiles(snapshotUrl, options);
 }
 export async function uploadTestingJobFiles(options) {
-    const body = {
+    if (options.branch !== undefined)
+        validateTestingGitRef(options.branch, 'branch');
+    const operations = options.operations.map((operation) => ({
+        ...operation,
+        path: normalizeRemotePath(operation.path),
+    }));
+    for (const operation of operations) {
+        if (operation.op === 'remove' && operation.value !== undefined) {
+            throw new Error('CRT remove file operations must not include content.');
+        }
+        if (operation.op !== 'remove' && operation.value === undefined) {
+            throw new Error(`CRT ${operation.op} file operations require content.`);
+        }
+    }
+    const uploadBytes = operations.reduce((total, operation) => total + Buffer.byteLength(operation.value ?? ''), 0);
+    if (uploadBytes > TESTING_UPLOAD_VALUE_MAX_BYTES) {
+        throw new Error(`CRT file upload exceeds the ${TESTING_UPLOAD_VALUE_MAX_BYTES} byte safety limit.`);
+    }
+    const body = omitUndefined({
         author: options.author ?? DEFAULT_TESTING_AUTHOR,
-        operations: options.operations,
-    };
+        commitMessage: options.commitMessage,
+        operations,
+        parentCommitHash: options.parentCommitHash,
+    });
+    if (options.dryRun === true) {
+        return {
+            dryRun: true,
+            operations: sanitizeTestingFilePlan(operations),
+            response: sanitizeTestingOutput({
+                author: body.author,
+                commitMessage: body.commitMessage,
+                parentCommitHash: body.parentCommitHash,
+            }),
+        };
+    }
     const response = await TestingGateway.call({
         body,
         endpoint: testingJobFilesUploadEndpoint(options.projectId, options.jobId, options.branch),
         method: 'POST',
         service: 'pace',
     }, options);
-    return { operations: options.operations, response: normalizeTestingRecord(response) };
+    return { operations: sanitizeTestingFilePlan(operations), response: sanitizeTestingOutput(normalizeTestingRecord(response)) };
+}
+export async function getTestingJobRefs(options) {
+    const response = await TestingGateway.call({
+        endpoint: testingJobRefsEndpoint(options.projectId, options.jobId, options.sharedCredentials),
+        method: 'GET',
+        service: 'pace',
+    }, options);
+    return sanitizeTestingOutput(normalizeTestingRecord(response));
 }
 export async function downloadTestingJobFiles(options) {
     const response = await TestingGateway.call({
@@ -227,34 +385,154 @@ export async function downloadTestingJobFiles(options) {
 }
 export async function runTestingBuild(options) {
     const body = buildTestingRunRequest(options);
+    const dataTableSelections = parseTestingDataTableRunSpecs(options.dataTables);
+    if (dataTableSelections.length > 0) {
+        const session = await createTestingDataSession(options);
+        const tables = await Promise.all(dataTableSelections.map((selection) => getTestingDataTable({
+            ...options,
+            jobId: undefined,
+            projectId: options.projectId,
+            session,
+            tableId: selection.tableId,
+        })));
+        const payloads = dataTableSelections[0]?.datasets.map((_, runIndex) => {
+            const inputParameters = [...(body.inputParameters ?? [])];
+            for (const [selectionIndex, selection] of dataTableSelections.entries()) {
+                const table = tables[selectionIndex];
+                const datasetIndex = selection.datasets[runIndex];
+                const headers = table?.data?.[0];
+                const dataset = datasetIndex === undefined ? undefined : table?.data?.[datasetIndex];
+                if (table === undefined || headers === undefined || dataset === undefined) {
+                    throw new Error(`Data table ${selection.tableId} does not contain selected dataset ${datasetIndex ?? '(unknown)'}.`);
+                }
+                for (const [column, header] of headers.entries()) {
+                    inputParameters.push({
+                        key: formatTestingDatasetKey(header, table.name ?? ''),
+                        type: 'dataset',
+                        value: dataset[column] ?? '',
+                    });
+                }
+            }
+            return {
+                ...body,
+                inputParameters: inputParameters.length > 0 ? inputParameters : undefined,
+                jobId: options.jobId,
+            };
+        }) ?? [];
+        const build = await TestingGateway.call({ body: payloads, endpoint: testingProjectBuildsEndpoint(options.projectId), method: 'POST', service: 'pace' }, options);
+        return {
+            body: sanitizeTestingOutput(payloads),
+            build: sanitizeTestingOutput(build),
+            dataDriven: true,
+            jobId: options.jobId,
+            projectId: options.projectId,
+        };
+    }
     const build = await TestingGateway.call({ body, endpoint: testingJobBuildsEndpoint(options.projectId, options.jobId), method: 'POST', service: 'pace' }, options);
-    return { body, build, jobId: options.jobId, projectId: options.projectId };
+    return {
+        body: sanitizeTestingOutput(body),
+        build: sanitizeTestingOutput(build),
+        jobId: options.jobId,
+        projectId: options.projectId,
+    };
 }
 export async function listTestingBuilds(options) {
     const endpoint = options.jobId === undefined
-        ? testingProjectBuildsEndpoint(options.projectId, { resultSize: options.resultSize, status: options.status })
-        : testingJobBuildsEndpoint(options.projectId, options.jobId, { resultSize: options.resultSize, status: options.status });
+        ? testingProjectBuildsEndpoint(options.projectId, {
+            page: options.page,
+            pageSize: options.pageSize,
+            resultSize: options.resultSize,
+            status: options.status,
+        })
+        : testingJobBuildsEndpoint(options.projectId, options.jobId, {
+            page: options.page,
+            pageSize: options.pageSize,
+            resultSize: options.resultSize,
+            status: options.status,
+        });
     const response = await TestingGateway.call({ endpoint, method: 'GET', service: 'pace' }, options);
     return normalizeTestingArray(response);
 }
+export async function countTestingBuilds(options) {
+    const result = await searchTestingBuilds({ ...options, count: true });
+    return result.count;
+}
+export async function getTestingBuild(options) {
+    return sanitizeTestingOutput(await getTestingBuildForArtifacts(options));
+}
+export async function getTestingBuildForArtifacts(options) {
+    const response = await TestingGateway.call({
+        endpoint: testingBuildEndpoint(options.projectId, options.jobId, options.buildId, { full: options.full }),
+        method: 'GET',
+        service: 'pace',
+    }, options);
+    return normalizeTestingEnvelopeRecord(response);
+}
+export async function latestTestingBuilds(options) {
+    const response = await TestingGateway.call({
+        endpoint: testingProjectBuildsEndpoint(options.projectId, {
+            resultSize: options.resultSize,
+            status: options.status,
+        }),
+        method: 'GET',
+        service: 'pace',
+    }, options);
+    return normalizeTestingArray(response);
+}
+export async function searchTestingBuilds(options) {
+    const credentials = resolveTestingCredentials(options);
+    const body = buildTestingMsearchBody(credentials.orgId, options);
+    const response = await TestingGateway.call({
+        body,
+        endpoint: testingMetricsSearchEndpoint(credentials.orgId),
+        headers: { 'Content-Type': 'application/x-ndjson' },
+        method: 'POST',
+        service: 'metrics',
+    }, options);
+    return normalizeTestingSearchResponse(response);
+}
 export async function waitForTestingBuildResult(options) {
     const timeoutMs = options.timeoutMs ?? TESTING_WAIT_TIMEOUT_MS;
     const deadline = Date.now() + timeoutMs;
     let attempts = 0;
     let intervalMs = options.intervalMs ?? TESTING_WAIT_INITIAL_INTERVAL_MS;
+    let log = '';
     while (Date.now() <= deadline) {
         attempts++;
-        const builds = await listTestingBuilds({
-            ...options,
-            jobId: options.jobId,
-            projectId: options.projectId,
-            resultSize: 'compact',
-        });
-        const build = findMatchingBuild(builds, options.buildId);
+        let build = options.streamLogs === true && options.buildId !== undefined
+            ? await getTestingBuild({
+                ...options,
+                buildId: options.buildId,
+                jobId: options.jobId,
+                projectId: options.projectId,
+            })
+            : findMatchingBuild(await listTestingBuilds({
+                ...options,
+                jobId: options.jobId,
+                projectId: options.projectId,
+                resultSize: 'compact',
+            }), options.buildId);
         if (build !== undefined) {
             options.onPoll?.(build);
+            if (options.streamLogs === true && options.buildId !== undefined && isTestingLogPollable(build)) {
+                const logResult = await getTestingBuildLogs({
+                    ...options,
+                    buildId: numericId(options.buildId, 'build'),
+                    jobId: options.jobId,
+                    knownSecrets: options.sensitiveValues,
+                    projectId: options.projectId,
+                });
+                if (logResult.log.length > log.length) {
+                    const chunk = logResult.log.slice(log.length);
+                    options.onLog?.(chunk);
+                    log = logResult.log;
+                }
+                if (logResult.status !== undefined && logResult.status.toLowerCase() !== 'executing') {
+                    build = { ...build, status: logResult.status };
+                }
+            }
             if (isTerminalBuild(build)) {
-                return { attempts, build, buildId: options.buildId, jobId: options.jobId, projectId: options.projectId };
+                return { attempts, build, buildId: options.buildId, jobId: options.jobId, log, projectId: options.projectId };
             }
         }
         await delay(Math.min(intervalMs, Math.max(deadline - Date.now(), 0)));
@@ -263,15 +541,22 @@ export async function waitForTestingBuildResult(options) {
     throw new Error(`Timed out waiting for CRT build result for job ${options.jobId}.`);
 }
 export async function getTestingBuildLogs(options) {
-    const log = await TestingGateway.call({
-        endpoint: testingBuildLogsEndpoint(options.projectId, options.jobId, options.buildId),
+    const response = await TestingGateway.call({
+        endpoint: testingBuildLogsEndpoint(options.projectId, options.jobId, options.buildId, options),
         method: 'GET',
         responseType: 'text',
         service: 'pace',
     }, options);
+    const normalized = normalizeTestingLogResponse(response);
+    const sanitizedLog = sanitizeTestingText(normalized.log, [
+        resolveTestingCredentials(options).pak,
+        ...(options.knownSecrets ?? []),
+    ]);
+    const log = options.tailLines === undefined ? sanitizedLog : tailTestingLogLines(sanitizedLog, options.tailLines);
     if (options.output !== undefined) {
-        mkdirSync(dirname(resolve(options.output)), { recursive: true });
-        writeFileSync(options.output, log, 'utf8');
+        const target = validateTestingOutputPath(options.output);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, log, 'utf8');
     }
     return {
         buildId: options.buildId,
@@ -279,8 +564,34 @@ export async function getTestingBuildLogs(options) {
         log,
         output: options.output,
         projectId: options.projectId,
+        status: normalized.status,
     };
 }
+export async function saveTestingBuildArtifacts(options) {
+    if (options.saveArtifacts === undefined && options.xunit === undefined)
+        return {};
+    const location = testingOutputArchiveLocation(options.build);
+    if (location === undefined)
+        throw new Error('No output archive found for this CRT build.');
+    const archive = await TestingGateway.downloadArtifact(location, options);
+    const result = {};
+    if (options.saveArtifacts !== undefined) {
+        const target = validateTestingOutputPath(options.saveArtifacts);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, archive);
+        result.archive = options.saveArtifacts;
+    }
+    if (options.xunit !== undefined) {
+        const target = validateTestingOutputPath(options.xunit);
+        const xunit = extractStoredOrDeflatedZipEntry(archive, 'xunit_report.xml');
+        if (xunit === undefined)
+            throw new Error('The CRT artifact archive does not contain xunit_report.xml.');
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, xunit);
+        result.xunit = options.xunit;
+    }
+    return result;
+}
 export async function abortTestingBuild(options) {
     const response = await TestingGateway.call({
         endpoint: testingBuildAbortEndpoint(options.projectId, options.jobId, options.buildId),
@@ -295,13 +606,31 @@ export async function abortTestingBuild(options) {
     };
 }
 export async function listTestingVariables(options) {
-    const response = await TestingGateway.call({ endpoint: testingVariablesEndpoint(options.projectId), method: 'GET', service: 'pace' }, options);
+    const endpoint = appendTestingQuery(testingVariablesEndpoint(options.projectId), {
+        jobId: options.jobId,
+        robotId: options.robotId,
+        sensitive: options.sensitive,
+        type: options.type,
+        userSpecific: options.userSpecific,
+    });
+    const response = await TestingGateway.call({ endpoint, method: 'GET', service: 'pace' }, options);
     const variables = normalizeTestingArray(response)
         .filter((variable) => options.jobId === undefined || variable.jobId?.toString() === options.jobId.toString())
-        .filter((variable) => options.robotId === undefined || variable.robotId?.toString() === options.robotId.toString());
+        .filter((variable) => options.robotId === undefined || variable.robotId?.toString() === options.robotId.toString())
+        .filter((variable) => options.key === undefined || variable.key === options.key)
+        .filter((variable) => options.sensitive === undefined || variable.sensitive === options.sensitive)
+        .filter((variable) => options.type === undefined || variable.type === options.type)
+        .filter((variable) => options.userSpecific === undefined || variable.userSpecific === options.userSpecific);
     return redactTestingVariables(variables);
 }
+export async function getTestingVariable(options) {
+    const response = await TestingGateway.call({ endpoint: testingVariableEndpoint(options.projectId, options.variableId), method: 'GET', service: 'pace' }, options);
+    return redactTestingVariables(normalizeTestingRecord(response));
+}
 export async function createTestingVariable(options) {
+    requireNonBlank(options.key, 'CRT variable key');
+    requireBoundedSecretValue(options.value, 'CRT variable value');
+    await ensureUniqueTestingVariable(options);
     const body = [omitUndefined({
             description: options.description,
             jobId: options.jobId,
@@ -324,6 +653,19 @@ export async function updateTestingVariable(options) {
         value: options.value,
     });
     requireBodyFields(body, 'Provide at least one variable field to update.');
+    requireBoundedSecretValue(options.value, 'CRT variable value');
+    if (options.key !== undefined)
+        requireNonBlank(options.key, 'CRT variable key');
+    if (options.key !== undefined) {
+        const current = await getTestingVariable(options);
+        await ensureUniqueTestingVariable({
+            jobId: numericField(current.jobId),
+            key: options.key,
+            projectId: options.projectId,
+            robotId: numericField(current.robotId),
+            userSpecific: typeof current.userSpecific === 'boolean' ? current.userSpecific : undefined,
+        }, options.variableId);
+    }
     const response = await TestingGateway.call({ body, endpoint: testingVariableEndpoint(options.projectId, options.variableId), method: 'PUT', service: 'pace' }, options);
     return redactTestingVariables(response);
 }
@@ -331,24 +673,77 @@ export async function deleteTestingVariable(options) {
     await TestingGateway.call({ endpoint: testingVariableEndpoint(options.projectId, options.variableId), method: 'DELETE', service: 'pace' }, options);
     return { projectId: options.projectId, variableId: options.variableId };
 }
+export async function listTestingUserParameters(options = {}) {
+    const response = await TestingGateway.call({ endpoint: testingUserParametersEndpoint(), method: 'GET', service: 'pace' }, options);
+    const parameters = normalizeTestingArray(response)
+        .filter((parameter) => options.key === undefined || parameter.key === options.key)
+        .filter((parameter) => options.projectId === undefined || parameter.projectId?.toString() === options.projectId.toString())
+        .filter((parameter) => options.jobId === undefined || parameter.jobId?.toString() === options.jobId.toString());
+    return redactTestingVariables(parameters);
+}
+export async function getTestingUserParameter(options) {
+    const response = await TestingGateway.call({ endpoint: testingUserParameterEndpoint(options.parameterId), method: 'GET', service: 'pace' }, options);
+    return redactTestingVariables(normalizeTestingRecord(response));
+}
+export async function createTestingUserParameter(options) {
+    requireNonBlank(options.key, 'CRT user-parameter key');
+    requireBoundedSecretValue(options.value, 'CRT user-parameter value');
+    if (options.unique === true)
+        await ensureUniqueTestingUserParameter(options.key, options);
+    const body = [omitUndefined({
+            description: options.description,
+            key: options.key,
+            keyIsUnique: options.unique === true ? true : options.keyIsUnique,
+            sensitive: options.sensitive ?? false,
+            type: options.type ?? 'parameter',
+            value: options.value,
+        })];
+    const response = await TestingGateway.call({ body, endpoint: testingUserParametersEndpoint(), method: 'POST', service: 'pace' }, options);
+    return redactTestingVariables(normalizeTestingArray(response)[0] ?? {});
+}
+export async function updateTestingUserParameter(options) {
+    const body = omitUndefined({ description: options.description, key: options.key, value: options.value });
+    requireBodyFields(body, 'Provide at least one user-parameter field to update.');
+    requireBoundedSecretValue(options.value, 'CRT user-parameter value');
+    if (options.key !== undefined)
+        requireNonBlank(options.key, 'CRT user-parameter key');
+    if (options.unique === true && options.key !== undefined) {
+        await ensureUniqueTestingUserParameter(options.key, options, options.parameterId);
+    }
+    const response = await TestingGateway.call({ body, endpoint: testingUserParameterEndpoint(options.parameterId), method: 'PUT', service: 'pace' }, options);
+    return redactTestingVariables(normalizeTestingRecord(response));
+}
+export async function deleteTestingUserParameter(options) {
+    await TestingGateway.call({ endpoint: testingUserParameterEndpoint(options.parameterId), method: 'DELETE', service: 'pace' }, options);
+    return { deleted: true, parameterId: options.parameterId };
+}
 export function buildFileAddOperations(input) {
     const operations = [];
     for (const file of input.files ?? []) {
-        operations.push(fileOperationFromLocalFile(file, basenameForPath(file), 'add'));
+        const remote = remotePathForLocalFile(file, input.basePath);
+        operations.push(fileOperationFromLocalFile(file, joinRemotePrefix(input.remotePrefix, remote), 'add', input.basePath));
     }
     for (const dir of input.dirs ?? []) {
         const root = resolve(dir);
+        if (input.basePath !== undefined)
+            assertLocalPathWithinBase(root, input.basePath);
         for (const file of collectFiles(root)) {
-            operations.push(fileOperationFromLocalFile(file, relative(root, file).split(sep).join('/'), 'add'));
+            const remote = input.basePath === undefined
+                ? relative(root, file).split(sep).join('/')
+                : remotePathForLocalFile(file, input.basePath);
+            operations.push(fileOperationFromLocalFile(file, joinRemotePrefix(input.remotePrefix, remote), 'add', input.basePath));
         }
     }
     return operations;
 }
 export function buildFileOperationsFromSpecs(specs) {
     return [
-        ...(specs.add ?? []).map((spec) => fileOperationFromSpec(spec, 'add')),
-        ...(specs.replace ?? []).map((spec) => fileOperationFromSpec(spec, 'replace')),
-        ...(specs.remove ?? []).map((path) => ({ op: 'remove', path: normalizeRemotePath(path) })),
+        ...(specs.add ?? []).map((spec) => fileOperationFromSpec(spec, 'add', specs)),
+        ...(specs.replace ?? []).map((spec) => fileOperationFromSpec(spec, 'replace', specs)),
+        ...(specs.remove ?? []).map((path) => ({
+            op: 'remove',
+            path: normalizeRemotePath(joinRemotePrefix(specs.remotePrefix, path)),
+        })),
     ];
 }
 export function buildTestingRunRequest(options) {
@@ -356,6 +751,21 @@ export function buildTestingRunRequest(options) {
         ...(options.parameters ?? []),
         ...(options.include ?? []).map((value) => ({ key: 'include', type: 'clp', value })),
         ...(options.exclude ?? []).map((value) => ({ key: 'exclude', type: 'clp', value })),
+        ...testingFlagParameters('--test', options.tests),
+        ...testingFlagParameters('--suite', options.suites),
+        ...testingFlagParameters('-v', options.variables),
+        ...testingFlagParameters('--skip', options.skip),
+        ...testingFlagParameters('--skiponfailure', options.skipOnFailure),
+        ...testingFlagParameters('--settag', options.setTags),
+        ...testingFlagParameters('--metadata', options.metadata),
+        ...testingBooleanParameter('--dryrun', options.dryRun),
+        ...testingBooleanParameter('--exitonerror', options.exitOnError),
+        ...testingBooleanParameter('--exitonfailure', options.exitOnFailure),
+        ...testingBooleanParameter('--runemptysuite', options.runEmptySuite),
+        ...testingScalarParameter('--name', options.name),
+        ...testingScalarParameter('--doc', options.doc),
+        ...testingScalarParameter('--consolewidth', options.consoleWidth),
+        ...testingScalarParameter('--consolecolors', normalizeConsoleColors(options.consoleColors)),
     ];
     return omitUndefined({
         branch: options.branch,
@@ -363,6 +773,7 @@ export function buildTestingRunRequest(options) {
         record: options.record,
         rerunFailedFromLatest: options.rerunFailedFromLatest,
         rerunFailedId: options.rerunFailedId,
+        runType: options.runType === 'regression' ? 'normal' : options.runType,
         tag: options.tag,
     });
 }
@@ -372,18 +783,22 @@ export function setTestingSnapshotFetchForTests(snapshotFetchFn) {
 export function resetTestingSnapshotFetchForTests() {
     testingSnapshotFetchFn = defaultTestingSnapshotFetch;
 }
-function fileOperationFromSpec(spec, op) {
+function fileOperationFromSpec(spec, op, options) {
     const separator = spec.indexOf(':');
     const localPath = separator === -1 ? spec : spec.slice(0, separator);
-    const remotePath = separator === -1 ? basenameForPath(localPath) : spec.slice(separator + 1);
-    return fileOperationFromLocalFile(localPath, remotePath, op);
+    const remotePath = separator === -1
+        ? remotePathForLocalFile(localPath, options.basePath)
+        : spec.slice(separator + 1);
+    return fileOperationFromLocalFile(localPath, joinRemotePrefix(options.remotePrefix, remotePath), op, options.basePath);
 }
-function fileOperationFromLocalFile(localPath, remotePath, op) {
+function fileOperationFromLocalFile(localPath, remotePath, op, basePath) {
     const path = normalizeRemotePath(remotePath);
     if (!existsSync(localPath))
         throw new Error(`Local CRT file does not exist: ${localPath}`);
     if (!statSync(localPath).isFile())
         throw new Error(`Local CRT path is not a file: ${localPath}`);
+    if (basePath !== undefined)
+        assertLocalPathWithinBase(localPath, basePath);
     return {
         encoding: 'utf-8',
         op,
@@ -406,13 +821,19 @@ function collectFiles(root) {
     }
     return files;
 }
-function normalizeRemotePath(path) {
-    const normalized = path.trim().replaceAll('\\', '/').replace(/^\/+/u, '');
-    if (normalized.length === 0 || normalized.includes('..')) {
+export function normalizeTestingRemotePath(path) {
+    const raw = path.trim().replaceAll('\\', '/');
+    if (raw.startsWith('/') || /^[a-z]:\//iu.test(raw)) {
+        throw new Error(`Invalid CRT file path: ${path}`);
+    }
+    const parts = raw.split('/');
+    if (raw.length === 0 || parts.some((part) => part.length === 0 || part === '.' || part === '..')) {
         throw new Error(`Invalid CRT file path: ${path}`);
     }
+    const normalized = parts.join('/');
     return normalized;
 }
+const normalizeRemotePath = normalizeTestingRemotePath;
 function writeDownloadedFiles(outputDir, files) {
     const root = resolve(outputDir);
     mkdirSync(root, { recursive: true });
@@ -432,6 +853,41 @@ function basenameForPath(path) {
     const segments = path.replaceAll('\\', '/').split('/').filter(Boolean);
     return segments.at(-1) ?? path;
 }
+function remotePathForLocalFile(localPath, basePath) {
+    if (basePath === undefined)
+        return basenameForPath(localPath);
+    if (!existsSync(localPath))
+        throw new Error(`Local CRT file does not exist: ${localPath}`);
+    assertLocalPathWithinBase(localPath, basePath);
+    const root = realpathSync(resolve(basePath));
+    const target = realpathSync(resolve(localPath));
+    assertPathWithinRoot(target, root, 'Local CRT file escapes --base-path');
+    return relative(root, target).split(sep).join('/');
+}
+function joinRemotePrefix(prefix, path) {
+    if (prefix === undefined || prefix.trim().length === 0)
+        return path;
+    return `${normalizeRemotePath(prefix)}/${path}`;
+}
+function assertLocalPathWithinBase(localPath, basePath) {
+    const root = resolve(basePath);
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        throw new Error(`CRT upload base path must be an existing directory: ${basePath}`);
+    }
+    assertPathWithinRoot(realpathSync(resolve(localPath)), realpathSync(root), 'Local CRT file escapes --base-path');
+}
+function assertPathWithinRoot(target, root, message) {
+    if (target !== root && !target.startsWith(`${root}${sep}`))
+        throw new Error(`${message}: ${target}`);
+}
+function sanitizeTestingFilePlan(operations) {
+    return operations.map((operation) => ({
+        encoding: operation.encoding,
+        op: operation.op,
+        path: operation.path,
+        ...(operation.value === undefined ? {} : { value: `[${Buffer.byteLength(operation.value)} bytes]` }),
+    }));
+}
 function filterByName(records, name, insensitive) {
     if (name === undefined || name.trim().length === 0)
         return records;
@@ -447,10 +903,28 @@ function findMatchingBuild(builds, buildId) {
     const expected = buildId.toString();
     return builds.find((build) => build.id?.toString() === expected || build.buildId?.toString() === expected);
 }
-function isTerminalBuild(build) {
-    const status = typeof build.status === 'string' ? build.status.toLowerCase() : undefined;
+export function testingBuildStatus(build) {
+    const direct = build.status;
+    const nestedResult = isPlainRecord(build.result) ? build.result.status : undefined;
+    const value = direct === 'finished' && typeof nestedResult === 'string'
+        ? nestedResult
+        : direct ?? build.buildStatus ?? build.state ?? nestedResult;
+    return typeof value === 'string' ? value.toLowerCase() : undefined;
+}
+export function isTerminalTestingBuild(build) {
+    const status = testingBuildStatus(build);
     return status !== undefined && TESTING_TERMINAL_BUILD_STATUSES.has(status);
 }
+export function isSuccessfulTestingBuild(build) {
+    return testingBuildStatus(build) === 'succeeded';
+}
+function isTerminalBuild(build) {
+    return isTerminalTestingBuild(build);
+}
+function isTestingLogPollable(build) {
+    const status = testingBuildStatus(build);
+    return status === 'executing' || status === 'finished' || status === 'succeeded';
+}
 async function delay(ms) {
     if (ms <= 0)
         return;
@@ -462,20 +936,41 @@ async function listTestingSnapshotFiles(snapshotUrl, options) {
     const credentials = resolveTestingCredentials(options);
     const transactionId = getGatewayTransactionId() ?? createTransactionId();
     const url = new URL(snapshotUrl);
+    validateTestingSnapshotUrl(url, credentials.domain);
     scheduleGatewayEventLog({
         eventId: transactionId,
         method: 'GET',
         orgId: credentials.orgId.toString(),
         service: CRT_GATEWAY_EVENT_SERVICE,
-        url: url.toString(),
+        url: sanitizeTestingUrl(url),
     });
     const snapshot = await testingSnapshotFetchFn(url, {
         Accept: 'application/octet-stream',
         ...gatewayRefererHeaders(),
         'X-Authorization': credentials.pak,
-    }, options.timeoutMs ?? TESTING_DEFAULT_TIMEOUT_MS);
+    }, options.timeoutMs ?? TESTING_DEFAULT_TIMEOUT_MS, TESTING_MAX_RESPONSE_BYTES);
+    if (snapshot.length > TESTING_MAX_RESPONSE_BYTES) {
+        throw new Error(`CRT snapshot response exceeded the ${TESTING_MAX_RESPONSE_BYTES} byte safety limit.`);
+    }
     return listSnapshotZipEntries(snapshot);
 }
+function validateTestingSnapshotUrl(url, domain) {
+    const expected = new URL(paceBaseUrl(domain));
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(url.pathname);
+    }
+    catch {
+        throw new Error('CRT snapshot URL has an invalid encoded path.');
+    }
+    if (url.protocol !== 'https:' ||
+        url.origin !== expected.origin ||
+        url.username.length > 0 ||
+        url.password.length > 0 ||
+        decodedPath.split('/').includes('..')) {
+        throw new Error('CRT snapshot URL must use the configured HTTPS Pace API host.');
+    }
+}
 function snapshotUrlForJob(job) {
     const { storage } = job;
     if (storage === null || typeof storage !== 'object' || Array.isArray(storage))
@@ -503,6 +998,61 @@ function requireBodyFields(body, message) {
     if (Object.keys(body).length === 0)
         throw new Error(message);
 }
+function requireNonBlank(value, label) {
+    if (value.trim().length === 0 || value.includes('\0'))
+        throw new Error(`${label} must not be blank.`);
+}
+function requireBoundedSecretValue(value, label) {
+    if (value !== undefined && Buffer.byteLength(value) > TESTING_SECRET_VALUE_MAX_BYTES) {
+        throw new Error(`${label} exceeds the ${TESTING_SECRET_VALUE_MAX_BYTES} byte safety limit.`);
+    }
+}
+function validateTestingPermissionRequest(request) {
+    if ((request.userId === undefined) === (request.groupId === undefined)) {
+        throw new Error('Provide exactly one of userId or groupId for a project permission.');
+    }
+    if (request.view !== true && request.edit !== true) {
+        throw new Error('Set view or edit to true for a project permission.');
+    }
+}
+async function ensureUniqueTestingVariable(options, excludedId) {
+    const matches = await listTestingVariables({
+        jobId: options.jobId,
+        key: options.key,
+        projectId: options.projectId,
+        robotId: options.robotId,
+        userSpecific: options.userSpecific,
+    });
+    const duplicate = matches.find((variable) => variable.id?.toString() !== excludedId &&
+        sameOptionalId(variable.jobId, options.jobId) &&
+        sameOptionalId(variable.robotId, options.robotId) &&
+        Boolean(variable.userSpecific) === Boolean(options.userSpecific));
+    if (duplicate !== undefined) {
+        throw new Error(`A CRT variable with key "${options.key}" already exists in this scope.`);
+    }
+}
+function sameOptionalId(left, right) {
+    if (left === undefined || left === null)
+        return right === undefined;
+    return right !== undefined && left.toString() === right.toString();
+}
+async function ensureUniqueTestingUserParameter(key, options, excludedId) {
+    const matches = await listTestingUserParameters({ ...options, key });
+    const duplicate = matches.find((parameter) => parameter.id?.toString() !== excludedId?.toString());
+    if (duplicate !== undefined) {
+        throw new Error(`A CRT user parameter with key "${key}" already exists.`);
+    }
+}
+function numericField(value) {
+    if (typeof value === 'number' && Number.isSafeInteger(value))
+        return value;
+    if (typeof value === 'string' && /^\d+$/u.test(value))
+        return Number.parseInt(value, 10);
+    return undefined;
+}
+function stringField(value) {
+    return typeof value === 'string' ? value : undefined;
+}
 function branchOrTagFromOptions(options) {
     if (options.gitBranch !== undefined)
         return { branch: options.gitBranch };
@@ -539,8 +1089,221 @@ function validateTestingGitStorageOptions(options, requirements) {
     if ((options.gitUsername === undefined) !== (options.gitPassword === undefined)) {
         throw new Error('Provide --git-username and --git-password together.');
     }
+    requireBoundedSecretValue(options.gitPassword, 'CRT Git password');
+    if (options.gitBranch !== undefined)
+        validateTestingGitRef(options.gitBranch, 'branch');
+    if (options.gitTag !== undefined)
+        validateTestingGitRef(options.gitTag, 'tag');
+}
+function validateTestingGitRef(value, label) {
+    if (value.length > 255 ||
+        value.trim() !== value ||
+        value.length === 0 ||
+        [...value].some((character) => {
+            const code = character.codePointAt(0) ?? 0;
+            return code < 32 || code === 127;
+        }) ||
+        /[ ~^:?*[\]\\]/u.test(value) ||
+        value.includes('..') ||
+        value.includes('@{') ||
+        value.startsWith('-') ||
+        value.endsWith('.') ||
+        value.endsWith('.lock') ||
+        value.split('/').some((part) => part.length === 0 || part.startsWith('.') || part.endsWith('.'))) {
+        throw new Error(`Invalid CRT Git ${label}.`);
+    }
 }
 function resolveOptions(options) {
     return { orgId: resolveTestingCredentials(options).orgId };
 }
+function testingFlagParameters(key, values) {
+    return (values ?? []).map((value) => ({ key, type: 'clp', value }));
+}
+function testingBooleanParameter(key, enabled) {
+    return enabled === true ? [{ key, type: 'clp', value: '' }] : [];
+}
+function testingScalarParameter(key, value) {
+    return value === undefined ? [] : [{ key, type: 'clp', value: value.toString() }];
+}
+function normalizeConsoleColors(value) {
+    return value === 'ansi' ? 'auto' : value;
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeTestingLogResponse(response) {
+    try {
+        const parsed = JSON.parse(response);
+        const record = normalizeTestingRecord(parsed);
+        const { log } = record;
+        const { status } = record;
+        if (typeof log === 'string') {
+            return { log, status: typeof status === 'string' ? status : undefined };
+        }
+    }
+    catch {
+        // Plain text is the backward-compatible CRT logs response.
+    }
+    return { log: response };
+}
+export function tailTestingLogLines(log, count) {
+    if (count === 0)
+        return '';
+    const lines = log.split('\n');
+    const hasTrailingNewline = lines.at(-1) === '';
+    if (hasTrailingNewline)
+        lines.pop();
+    if (lines.length <= count)
+        return log;
+    const result = lines.slice(-count).join('\n');
+    return hasTrailingNewline ? `${result}\n` : result;
+}
+export function validateTestingOutputPath(path) {
+    if (path.trim().length === 0 || path.includes('\0'))
+        throw new Error('CRT output path must not be empty.');
+    const target = resolve(path);
+    if (existsSync(target) && statSync(target).isDirectory()) {
+        throw new Error(`CRT output path must be a file: ${path}`);
+    }
+    return target;
+}
+function testingOutputArchiveLocation(build) {
+    const candidates = [
+        build.outputArchive,
+        build.output_archive,
+        build.artifactUrl,
+        build.artifact_url,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim().length > 0)
+            return candidate;
+        if (isPlainRecord(candidate)) {
+            for (const value of [candidate.location, candidate.url, candidate.href]) {
+                if (typeof value === 'string' && value.trim().length > 0)
+                    return value;
+            }
+        }
+    }
+    return undefined;
+}
+function extractStoredOrDeflatedZipEntry(archive, expectedName) {
+    const centralOffset = centralDirectoryOffsetForExtraction(archive);
+    if (centralOffset === undefined)
+        throw new Error('CRT artifact is not a valid ZIP archive.');
+    let offset = centralOffset;
+    while (offset + 46 <= archive.length && archive.readUInt32LE(offset) === 0x02_01_4b_50) {
+        const method = archive.readUInt16LE(offset + 10);
+        const compressedSize = archive.readUInt32LE(offset + 20);
+        const nameLength = archive.readUInt16LE(offset + 28);
+        const extraLength = archive.readUInt16LE(offset + 30);
+        const commentLength = archive.readUInt16LE(offset + 32);
+        const localOffset = archive.readUInt32LE(offset + 42);
+        const name = archive.subarray(offset + 46, offset + 46 + nameLength).toString('utf8');
+        if (name === expectedName || name.endsWith(`/${expectedName}`)) {
+            if (localOffset + 30 > archive.length || archive.readUInt32LE(localOffset) !== 0x04_03_4b_50) {
+                throw new Error('CRT artifact contains an invalid ZIP entry.');
+            }
+            const localNameLength = archive.readUInt16LE(localOffset + 26);
+            const localExtraLength = archive.readUInt16LE(localOffset + 28);
+            const dataOffset = localOffset + 30 + localNameLength + localExtraLength;
+            const compressed = archive.subarray(dataOffset, dataOffset + compressedSize);
+            if (compressed.length !== compressedSize)
+                throw new Error('CRT artifact contains a truncated ZIP entry.');
+            if (method === 0)
+                return Buffer.from(compressed);
+            if (method === 8)
+                return inflateRawSync(compressed);
+            throw new Error(`CRT xUnit extraction does not support ZIP compression method ${method}.`);
+        }
+        offset += 46 + nameLength + extraLength + commentLength;
+    }
+    return undefined;
+}
+function centralDirectoryOffsetForExtraction(archive) {
+    for (let offset = archive.length - 22; offset >= 0; offset--) {
+        if (archive.readUInt32LE(offset) === 0x06_05_4b_50)
+            return archive.readUInt32LE(offset + 16);
+    }
+    return undefined;
+}
+export function buildTestingMsearchBody(orgId, options) {
+    const filters = [
+        { term: { projectId: options.projectId } },
+        { term: { jobId: options.jobId } },
+    ];
+    if ((options.statuses?.length ?? 0) > 0)
+        filters.push({ terms: { 'categories.state.keyword': options.statuses } });
+    if ((options.runTypes?.length ?? 0) > 0) {
+        filters.push({
+            terms: {
+                'runType.keyword': options.runTypes?.map((runType) => (runType === 'regression' ? 'normal' : 'development')),
+            },
+        });
+    }
+    if ((options.robots?.length ?? 0) > 0)
+        filters.push({ terms: { 'categories.robotId.keyword': options.robots } });
+    if (options.from !== undefined || options.to !== undefined) {
+        filters.push({ range: { date: omitUndefined({ gte: options.from, lte: options.to }) } });
+    }
+    const sortFields = {
+        date: 'date',
+        duration: 'testExecutionTime',
+        id: 'buildNumber',
+        status: 'categories.state.keyword',
+    };
+    const page = Math.max(1, options.page ?? 1);
+    const pageSize = options.pageSize ?? 50;
+    const query = {
+        _source: [
+            'buildNumber',
+            'categories.state',
+            'categories.jobName',
+            'categories.robotId',
+            'runType',
+            'date',
+            'testExecutionTime',
+        ],
+        from: (page - 1) * pageSize,
+        query: { bool: { filter: filters } },
+        size: options.count === true ? 0 : pageSize,
+        sort: [{ [sortFields[options.sort ?? 'date']]: { order: options.order ?? 'desc' } }],
+        // Metrics API follows the Elasticsearch wire name.
+        // eslint-disable-next-line camelcase
+        track_total_hits: true,
+    };
+    return `${JSON.stringify({ index: `org_${orgId}_type_testresults` })}\n${JSON.stringify(query)}\n`;
+}
+function normalizeTestingSearchResponse(response) {
+    const root = normalizeTestingRecord(response);
+    const responses = Array.isArray(root.responses) ? root.responses : [];
+    const first = isPlainRecord(responses[0]) ? responses[0] : {};
+    const hits = isPlainRecord(first.hits) ? first.hits : {};
+    const totalRecord = isPlainRecord(hits.total) ? hits.total : {};
+    const totalValue = totalRecord.value ?? hits.total;
+    const count = typeof totalValue === 'number'
+        ? totalValue
+        : typeof totalValue === 'string' && /^\d+$/u.test(totalValue)
+            ? Number.parseInt(totalValue, 10)
+            : 0;
+    const documents = Array.isArray(hits.hits) ? hits.hits : [];
+    const runs = documents
+        .map((document) => (isPlainRecord(document) && isPlainRecord(document._source) ? document._source : document))
+        .filter((document) => isPlainRecord(document))
+        .map((source) => normalizeTestingSearchBuild(source));
+    return { count, runs };
+}
+function normalizeTestingSearchBuild(source) {
+    const categories = isPlainRecord(source.categories) ? source.categories : {};
+    const id = source.buildNumber ?? source.id;
+    const jobId = source.jobId ?? categories.jobId;
+    const status = categories.state ?? source.status;
+    const runType = source.runType === 'normal' ? 'regression' : source.runType;
+    return {
+        ...source,
+        id: typeof id === 'number' || typeof id === 'string' ? id : undefined,
+        jobId: typeof jobId === 'number' || typeof jobId === 'string' ? jobId : undefined,
+        runType: typeof runType === 'string' ? runType : undefined,
+        status: typeof status === 'string' ? status : undefined,
+    };
+}
 //# sourceMappingURL=testing-operations.js.map