agent-scenario-loop 0.1.0

package/dist/runner/android-adb.d.ts

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+type CliArgs = {
+    adb?: string | boolean;
+    'capture-logcat'?: string | boolean;
+    'clear-logcat'?: string | boolean;
+    launch?: string | boolean;
+    'android-dev-client-url'?: string | boolean;
+    'android-dev-client-wait-ms'?: string | boolean;
+    'android-dev-client-ready-pattern'?: string | boolean;
+    'android-dev-client-ready-quiet-ms'?: string | boolean;
+    'android-dev-client-ready-timeout-ms'?: string | boolean;
+    'android-profile-session-storage'?: string | boolean;
+    'android-profile-session-storage-key'?: string | boolean;
+    'android-profile-command-storage-key'?: string | boolean;
+    'launch-wait-ms'?: string | boolean;
+    'logcat-lines'?: string | boolean;
+    out?: string | boolean;
+    package?: string | boolean;
+    'react-native-debug-host'?: string | boolean;
+    'run-id'?: string | boolean;
+    serial?: string | boolean;
+    'wait-ms'?: string | boolean;
+    [key: string]: string | boolean | undefined;
+};
+type CommandResult = {
+    command: string;
+    args: string[];
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+};
+type CommandExecutor = (command: string, args: string[]) => Promise<CommandResult>;
+type AndroidDevice = {
+    serial: string;
+    state: string;
+    description: string;
+};
+type AndroidPreflightResult = {
+    agentSummary: string;
+    device: AndroidDevice | null;
+    health: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    raw: Record<string, string>;
+    runDir: string;
+    verdict: Record<string, unknown>;
+};
+type AndroidDeepLinkCommand = {
+    label?: string;
+    readyLogPattern?: string;
+    readyLogQuietMs?: number;
+    readyLogTimeoutMs?: number;
+    url: string;
+    waitMs?: number;
+};
+type AndroidAsyncStorageWrite = {
+    clearKeys?: string[];
+    key: string;
+    label?: string;
+    value: string;
+    waitMs?: number;
+};
+type AndroidAdbDriverStep = {
+    captureFileName?: string;
+    driverAction: 'assertVisible' | 'inspectTree' | 'readLogs' | 'record' | 'screenshot' | 'scroll' | 'tap';
+    durationMs?: number;
+    durationSeconds?: number;
+    endX?: number;
+    endY?: number;
+    lines?: number;
+    rawFileName?: string;
+    remotePath?: string;
+    required?: boolean;
+    selector?: import('./android-adb-driver').AndroidSelector;
+    stepId?: string;
+    startX?: number;
+    startY?: number;
+    waitMs?: number;
+    x?: number;
+    y?: number;
+};
+type AndroidPreflightOptions = {
+    adbPath?: string;
+    captureLogcat?: boolean;
+    clearLogcat?: boolean;
+    deepLinks?: AndroidDeepLinkCommand[];
+    delay?: (ms: number) => Promise<void>;
+    driverSteps?: AndroidAdbDriverStep[];
+    executor?: CommandExecutor;
+    launch?: boolean;
+    launchWaitMs?: number;
+    logcatLines?: number;
+    outputDir?: string;
+    packageName?: string | null;
+    reactNativeDebugHost?: string | null;
+    runId?: string;
+    serial?: string | null;
+    startupDeepLinks?: AndroidDeepLinkCommand[];
+    storageWrites?: AndroidAsyncStorageWrite[];
+    waitMs?: number;
+};
+declare const ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER = "__ASL_ANDROID_DEVICE_EPOCH_MS__";
+/**
+ * Prints CLI usage to stderr.
+ *
+ * @returns {void}
+ */
+declare function usage(output?: {
+    write: (message: string) => unknown;
+}): void;
+/**
+ * Parses `--key value` arguments for the Android adb preflight CLI.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Parses a positive integer CLI value, falling back when absent or invalid.
+ *
+ * @param {string | boolean | undefined} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+declare function parsePositiveInteger(value: string | boolean | undefined, fallback: number): number;
+/**
+ * Runs a command and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<CommandResult>}
+ */
+declare function execFileCommand(command: string, args: string[]): Promise<CommandResult>;
+/**
+ * Parses `adb devices -l` output into device rows.
+ *
+ * @param {string} output
+ * @returns {AndroidDevice[]}
+ */
+declare function parseAdbDevices(output: string): AndroidDevice[];
+/**
+ * Selects an Android device by explicit serial or first online device.
+ *
+ * @param {AndroidDevice[]} devices
+ * @param {string | null | undefined} serial
+ * @returns {AndroidDevice | null}
+ */
+declare function selectDevice(devices: AndroidDevice[], serial?: string | null): AndroidDevice | null;
+/**
+ * Reads the TCP port from a React Native debug server host string.
+ *
+ * @param {string} debugHost
+ * @returns {number | null}
+ */
+declare function parseReactNativeDebugHostPort(debugHost: string): number | null;
+/**
+ * Escapes text for the Android shared preference XML file.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+declare function escapeAndroidPreferenceXml(value: string): string;
+/**
+ * Builds a device-side shell command that writes React Native debug host preferences.
+ *
+ * @param {{debugHost: string, packageName: string}} options
+ * @returns {string}
+ */
+declare function buildReactNativeDebugHostPreferenceCommand({ debugHost, packageName, }: {
+    debugHost: string;
+    packageName: string;
+}): string;
+/**
+ * Builds a runner health artifact from adb preflight checks.
+ *
+ * @param {{runId: string, checks: Record<string, unknown>[]}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildAndroidHealth({ runId, checks }: {
+    runId: string;
+    checks: Record<string, unknown>[];
+}): Record<string, unknown>;
+/**
+ * Builds a verdict artifact for adb preflight readiness.
+ *
+ * @param {{runId: string, health: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+declare function buildAndroidVerdict({ runId, health }: {
+    runId: string;
+    health: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * Builds the driver steps for this adb capture window.
+ *
+ * @param {{captureLogcat: boolean, driverSteps: AndroidAdbDriverStep[], logcatLines: number, waitMs: number}} options
+ * @returns {AndroidAdbDriverStep[]}
+ */
+declare function resolveAndroidAdbDriverSteps({ captureLogcat, driverSteps, logcatLines, waitMs, }: {
+    captureLogcat: boolean;
+    driverSteps: AndroidAdbDriverStep[];
+    logcatLines: number;
+    waitMs: number;
+}): AndroidAdbDriverStep[];
+/**
+ * Returns whether a driver step can derive missing coordinates from a selector.
+ *
+ * @param {AndroidAdbDriverStep} driverStep
+ * @returns {boolean}
+ */
+declare function needsAndroidSelectorResolution(driverStep: AndroidAdbDriverStep): boolean;
+/**
+ * Applies a resolved selector to one tap or scroll driver step.
+ *
+ * @param {{driverStep: AndroidAdbDriverStep, resolution: import('./android-adb-driver').AndroidSelectorResolution}} options
+ * @returns {AndroidAdbDriverStep}
+ */
+declare function applyAndroidSelectorResolution({ driverStep, resolution, }: {
+    driverStep: AndroidAdbDriverStep;
+    resolution: import('./android-adb-driver').AndroidSelectorResolution;
+}): AndroidAdbDriverStep;
+/**
+ * Converts a selector into scalar health-check metadata fields.
+ *
+ * @param {import('./android-adb-driver').AndroidSelector | undefined} selector
+ * @returns {Record<string, string>}
+ */
+declare function buildAndroidSelectorHealthMetadata(selector: import('./android-adb-driver').AndroidSelector | undefined): Record<string, string>;
+/**
+ * Runs one normalized adb driver step through the Android driver adapter.
+ *
+ * @param {{driver: import('./android-adb-driver').AndroidAdbDriver, driverStep: AndroidAdbDriverStep, logcatLines: number}} options
+ * @returns {Promise<import('./android-adb-driver').AndroidAdbCommandResult>}
+ */
+declare function runAndroidAdbDriverStep({ capturesDir, driver, driverStep, logcatLines, }: {
+    capturesDir: string;
+    driver: import('./android-adb-driver').AndroidAdbDriver;
+    driverStep: AndroidAdbDriverStep;
+    logcatLines: number;
+}): Promise<import('./android-adb-driver').AndroidAdbCommandResult>;
+/**
+ * Runs Android adb readiness checks and writes the preflight artifact set.
+ *
+ * @param {AndroidPreflightOptions} options
+ * @returns {Promise<AndroidPreflightResult>}
+ */
+declare function runAndroidAdbPreflight({ adbPath, captureLogcat, clearLogcat, deepLinks, delay: wait, driverSteps, executor, launch, launchWaitMs, logcatLines, outputDir, packageName, reactNativeDebugHost, runId, serial, startupDeepLinks, storageWrites, waitMs, }?: AndroidPreflightOptions): Promise<AndroidPreflightResult>;
+/**
+ * Runs the android-adb preflight CLI.
+ *
+ * @returns {Promise<void>}
+ */
+declare function main(): Promise<void>;
+export { ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER, buildAndroidHealth, buildAndroidVerdict, buildReactNativeDebugHostPreferenceCommand, escapeAndroidPreferenceXml, execFileCommand, main, parseAdbDevices, parseArgs, parsePositiveInteger, parseReactNativeDebugHostPort, resolveAndroidAdbDriverSteps, applyAndroidSelectorResolution, buildAndroidSelectorHealthMetadata, needsAndroidSelectorResolution, runAndroidAdbDriverStep, runAndroidAdbPreflight, selectDevice, usage, };
+export type { AndroidDevice, AndroidAdbDriverStep, AndroidAsyncStorageWrite, AndroidDeepLinkCommand, AndroidPreflightOptions, AndroidPreflightResult, CliArgs, CommandExecutor, CommandResult, };