agent-device 0.14.2 → 0.14.4

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

@@ -0,0 +1,190 @@
+import fs from 'node:fs';
+import type { Readable } from 'node:stream';
+import { SpawnOptions } from 'node:child_process';
+import type { Writable } from 'node:stream';
+
+/**
+ * Runs device-scoped adb arguments after the device serial has already been selected.
+ * Implementations must be safe to call concurrently for one request.
+ */
+export declare type AndroidAdbExecutor = (args: string[], options?: AndroidAdbExecutorOptions) => Promise<AndroidAdbExecutorResult>;
+
+export declare type AndroidAdbExecutorOptions = Pick<ExecOptions, 'allowFailure' | 'timeoutMs' | 'binaryStdout' | 'stdin' | 'signal'>;
+
+export declare type AndroidAdbExecutorResult = Pick<ExecResult, 'exitCode' | 'stdout' | 'stderr' | 'stdoutBuffer'>;
+
+/**
+ * Installs an APK path. Implementations are responsible for honoring semantic
+ * install options such as replace/test/downgrade/grant-permissions.
+ */
+export declare type AndroidAdbInstaller = (apkPath: string, options?: AndroidAdbInstallOptions) => Promise<AndroidAdbExecutorResult>;
+
+export declare type AndroidAdbInstallOptions = AndroidAdbTransferOptions & {
+    replace?: boolean;
+    allowTestPackages?: boolean;
+    allowDowngrade?: boolean;
+    grantPermissions?: boolean;
+};
+
+export declare type AndroidAdbProcess = {
+    pid?: number;
+    stdin: Writable | null;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    killed: boolean;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once(event: 'exit' | 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'exit' | 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+};
+
+export declare type AndroidAdbProvider = {
+    /**
+     * Fallback executor for device-scoped adb arguments. Providers may omit explicit
+     * methods to keep the legacy exec-shaped pull/install fallback.
+     */
+    exec: AndroidAdbExecutor;
+    spawn?: AndroidAdbSpawner;
+    reverse?: AndroidPortReverseProvider;
+    pull?: AndroidAdbPuller;
+    install?: AndroidAdbInstaller;
+};
+
+export declare type AndroidAdbPuller = (remotePath: string, localPath: string, options?: AndroidAdbTransferOptions) => Promise<AndroidAdbExecutorResult>;
+
+export declare type AndroidAdbSpawner = (args: string[], options?: SpawnOptions) => AndroidAdbProcess;
+
+export declare type AndroidAdbTransferOptions = AndroidAdbExecutorOptions;
+
+export declare type AndroidAppListFilter = 'user-installed' | 'all';
+
+export declare type AndroidAppListOptions = {
+    filter?: AndroidAppListFilter;
+    target?: AndroidAppListTarget;
+};
+
+export declare type AndroidAppListTarget = 'mobile' | 'tv' | 'auto';
+
+declare type AndroidForegroundApp = {
+    package?: string;
+    activity?: string;
+};
+
+export declare type AndroidKeyboardState = {
+    visible: boolean;
+    inputType?: string;
+    type?: AndroidKeyboardType;
+};
+
+declare type AndroidKeyboardType = 'text' | 'number' | 'email' | 'phone' | 'password' | 'datetime' | 'unknown';
+
+export declare type AndroidLogcatCaptureOptions = {
+    lines?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+
+export declare type AndroidLogcatStreamOptions = {
+    pid?: string;
+    signal?: AbortSignal;
+    output?: fs.WriteStream;
+};
+
+export declare type AndroidOpenAppWithAdbOptions = {
+    activity?: string;
+    category?: string;
+};
+
+export declare type AndroidPortReverseEndpoint = `tcp:${number}` | `localabstract:${string}`;
+
+export declare type AndroidPortReverseMapping = {
+    local: AndroidPortReverseEndpoint;
+    remote: AndroidPortReverseEndpoint;
+    ownerId?: string;
+};
+
+export declare type AndroidPortReverseOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+
+export declare type AndroidPortReverseProvider = {
+    ensure(mapping: AndroidPortReverseMapping, options?: AndroidPortReverseOptions): Promise<void>;
+    remove(local: AndroidPortReverseEndpoint, options?: AndroidPortReverseOptions): Promise<void>;
+    removeAllOwned(ownerId: string, options?: AndroidPortReverseOptions): Promise<void>;
+    list?(options?: AndroidPortReverseOptions): Promise<AndroidPortReverseMapping[]>;
+};
+
+declare type ApplePlatform = 'ios' | 'macos';
+
+export declare function captureAndroidLogcatWithAdb(adb: AndroidAdbExecutor, options?: AndroidLogcatCaptureOptions): Promise<string>;
+
+export declare function createAndroidPortReverseManager(provider: AndroidAdbProvider | AndroidAdbExecutor): AndroidPortReverseProvider;
+
+export declare function createLocalAndroidAdbProvider(device: DeviceInfo): AndroidAdbProvider;
+
+declare type DeviceInfo = {
+    platform: Platform;
+    id: string;
+    name: string;
+    kind: DeviceKind;
+    target?: DeviceTarget;
+    booted?: boolean;
+    simulatorSetPath?: string;
+};
+
+declare type DeviceKind = 'simulator' | 'emulator' | 'device';
+
+declare type DeviceTarget = 'mobile' | 'tv' | 'desktop';
+
+export declare function dismissAndroidKeyboardWithAdb(adb: AndroidAdbExecutor): Promise<{
+    attempts: number;
+    wasVisible: boolean;
+    dismissed: boolean;
+    visible: boolean;
+    inputType?: string;
+    type?: AndroidKeyboardType;
+}>;
+
+declare type ExecOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    allowFailure?: boolean;
+    binaryStdout?: boolean;
+    stdin?: string | Buffer;
+    timeoutMs?: number;
+    detached?: boolean;
+    signal?: AbortSignal;
+};
+
+declare type ExecResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    stdoutBuffer?: Buffer;
+};
+
+export declare function forceStopAndroidAppWithAdb(adb: AndroidAdbExecutor, packageName: string): Promise<void>;
+
+export declare function getAndroidAppStateWithAdb(adb: AndroidAdbExecutor): Promise<AndroidForegroundApp>;
+
+export declare function getAndroidKeyboardStatusWithAdb(adb: AndroidAdbExecutor): Promise<AndroidKeyboardState>;
+
+export declare function listAndroidAppsWithAdb(adb: AndroidAdbExecutor, options?: AndroidAppListOptions): Promise<Array<{
+    package: string;
+    name: string;
+}>>;
+
+export declare function openAndroidAppWithAdb(adb: AndroidAdbExecutor, packageName: string, options?: AndroidOpenAppWithAdbOptions): Promise<void>;
+
+declare type Platform = ApplePlatform | 'android' | 'linux';
+
+export declare function readAndroidClipboardWithAdb(adb: AndroidAdbExecutor): Promise<string>;
+
+export declare function resolveAndroidLaunchComponentWithAdb(adb: AndroidAdbExecutor, packageName: string, categories?: string[]): Promise<string | null>;
+
+export declare function streamAndroidLogcatWithAdb(provider: Pick<AndroidAdbProvider, 'spawn'>, options?: AndroidLogcatStreamOptions): AndroidAdbProcess;
+
+export declare function writeAndroidClipboardWithAdb(adb: AndroidAdbExecutor, text: string): Promise<void>;
+
+export { }

package/dist/src/android-adb.js

@@ -0,0 +1 @@
+import{AppError as t}from"./9152.js";import{parseAndroidForegroundApp as e,parseAndroidLaunchablePackages as i,parseAndroidUserInstalledPackages as a,inferAndroidAppName as r,parseAndroidLaunchComponent as o,isAmStartError as n}from"./8809.js";let d="android.intent.category.LAUNCHER",l="android.intent.category.LEANBACK_LAUNCHER";async function s(t,e={}){let i=await u(t,e.target??"auto");return("user-installed"===e.filter?(await A(t)).filter(t=>i.has(t)):Array.from(i)).map(t=>({package:t,name:r(t)})).sort((t,e)=>t.package.localeCompare(e.package))}async function c(t){let e=await p(t,[["shell","dumpsys","window","windows"],["shell","dumpsys","window"]]);if(e)return e;let i=await p(t,[["shell","dumpsys","activity","activities"],["shell","dumpsys","activity"]]);return i||{}}async function u(t,e){return new Set((await Promise.all((function(t){switch(t){case"mobile":return[d];case"tv":return[l];default:return[d,l]}})(e).map(async e=>{var a;let r=await t(["shell","cmd","package","query-activities","--brief","-a","android.intent.action.MAIN","-c",e],{allowFailure:!0});return 0===r.exitCode?0===(a=r.stdout).trim().length?[]:i(a):[]}))).flat())}async function A(e){let i=await e(["shell","pm","list","packages","-3"],{allowFailure:!0});if(0!==i.exitCode)throw new t("COMMAND_FAILED","Failed to list Android user-installed apps",{stdout:i.stdout,stderr:i.stderr,exitCode:i.exitCode});return a(i.stdout)}async function p(t,i){for(let a of i){let i=e((await t(a,{allowFailure:!0})).stdout??"");if(i)return i}return null}let f="android.intent.category.LAUNCHER",w="android.intent.category.DEFAULT";async function h(t,e){await t(["shell","am","force-stop",e])}async function m(t,e,i=[f]){for(let a of i){let i=await t(["shell","cmd","package","resolve-activity","--brief","-a","android.intent.action.MAIN","-c",a,e],{allowFailure:!0});if(0!==i.exitCode)continue;let r=o(i.stdout);if(r)return r}return null}async function C(e,i,a={}){let r=a.category??f;if(a.activity){var o,d;return void await e(["shell","am","start","-W","-a","android.intent.action.MAIN","-c",w,"-c",r,"-n",(o=i,(d=a.activity).includes("/")?d:`${o}/${d.startsWith(".")?d:`.${d}`}`)])}let l=await e(["shell","am","start","-W","-a","android.intent.action.MAIN","-c",w,"-c",r,"-p",i],{allowFailure:!0});if(0===l.exitCode&&!n(l.stdout,l.stderr))return;let s=await m(e,i,[r]);if(!s)throw new t("COMMAND_FAILED",`Failed to resolve Android launch component for ${i}`,{stdout:l.stdout,stderr:l.stderr,exitCode:l.exitCode});await e(["shell","am","start","-W","-a","android.intent.action.MAIN","-c",w,"-c",r,"-n",s])}export{captureAndroidLogcatWithAdb,streamAndroidLogcatWithAdb}from"./6642.js";export{createAndroidPortReverseManager,createLocalAndroidAdbProvider}from"./9639.js";export{dismissAndroidKeyboardWithAdb,getAndroidKeyboardStatusWithAdb,readAndroidClipboardWithAdb,writeAndroidClipboardWithAdb}from"./8809.js";export{h as forceStopAndroidAppWithAdb,c as getAndroidAppStateWithAdb,s as listAndroidAppsWithAdb,C as openAndroidAppWithAdb,m as resolveAndroidLaunchComponentWithAdb};

package/dist/src/android-snapshot-helper.d.ts

@@ -1,3 +1,7 @@
+import type { Readable } from 'node:stream';
+import { SpawnOptions } from 'node:child_process';
+import type { Writable } from 'node:stream';
+
 export declare const ANDROID_SNAPSHOT_HELPER_NAME = "android-snapshot-helper";
 
 export declare const ANDROID_SNAPSHOT_HELPER_OUTPUT_FORMAT = "uiautomator-xml";
@@ -10,14 +14,78 @@ export declare const ANDROID_SNAPSHOT_HELPER_RUNNER = "com.callstack.agentdevice
 
 export declare const ANDROID_SNAPSHOT_HELPER_WAIT_FOR_IDLE_TIMEOUT_MS = 500;
 
-export declare type AndroidAdbExecutor = (args: string[], options?: {
-    allowFailure?: boolean;
+/**
+ * Runs device-scoped adb arguments after the device serial has already been selected.
+ * Implementations must be safe to call concurrently for one request.
+ */
+export declare type AndroidAdbExecutor = (args: string[], options?: AndroidAdbExecutorOptions) => Promise<AndroidAdbExecutorResult>;
+
+declare type AndroidAdbExecutorOptions = Pick<ExecOptions, 'allowFailure' | 'timeoutMs' | 'binaryStdout' | 'stdin' | 'signal'>;
+
+declare type AndroidAdbExecutorResult = Pick<ExecResult, 'exitCode' | 'stdout' | 'stderr' | 'stdoutBuffer'>;
+
+/**
+ * Installs an APK path. Implementations are responsible for honoring semantic
+ * install options such as replace/test/downgrade/grant-permissions.
+ */
+declare type AndroidAdbInstaller = (apkPath: string, options?: AndroidAdbInstallOptions) => Promise<AndroidAdbExecutorResult>;
+
+declare type AndroidAdbInstallOptions = AndroidAdbTransferOptions & {
+    replace?: boolean;
+    allowTestPackages?: boolean;
+    allowDowngrade?: boolean;
+    grantPermissions?: boolean;
+};
+
+declare type AndroidAdbProcess = {
+    pid?: number;
+    stdin: Writable | null;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    killed: boolean;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    once(event: 'exit' | 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    on(event: 'exit' | 'close', listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+};
+
+declare type AndroidAdbProvider = {
+    /**
+     * Fallback executor for device-scoped adb arguments. Providers may omit explicit
+     * methods to keep the legacy exec-shaped pull/install fallback.
+     */
+    exec: AndroidAdbExecutor;
+    spawn?: AndroidAdbSpawner;
+    reverse?: AndroidPortReverseProvider;
+    pull?: AndroidAdbPuller;
+    install?: AndroidAdbInstaller;
+};
+
+declare type AndroidAdbPuller = (remotePath: string, localPath: string, options?: AndroidAdbTransferOptions) => Promise<AndroidAdbExecutorResult>;
+
+declare type AndroidAdbSpawner = (args: string[], options?: SpawnOptions) => AndroidAdbProcess;
+
+declare type AndroidAdbTransferOptions = AndroidAdbExecutorOptions;
+
+declare type AndroidPortReverseEndpoint = `tcp:${number}` | `localabstract:${string}`;
+
+declare type AndroidPortReverseMapping = {
+    local: AndroidPortReverseEndpoint;
+    remote: AndroidPortReverseEndpoint;
+    ownerId?: string;
+};
+
+declare type AndroidPortReverseOptions = {
+    signal?: AbortSignal;
     timeoutMs?: number;
-}) => Promise<{
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-}>;
+};
+
+declare type AndroidPortReverseProvider = {
+    ensure(mapping: AndroidPortReverseMapping, options?: AndroidPortReverseOptions): Promise<void>;
+    remove(local: AndroidPortReverseEndpoint, options?: AndroidPortReverseOptions): Promise<void>;
+    removeAllOwned(ownerId: string, options?: AndroidPortReverseOptions): Promise<void>;
+    list?(options?: AndroidPortReverseOptions): Promise<AndroidPortReverseMapping[]>;
+};
 
 declare type AndroidSnapshotAnalysis = {
     rawNodeCount: number;
@@ -121,12 +189,31 @@ export declare function captureAndroidSnapshotWithHelper(options: AndroidSnapsho
 
 export declare function ensureAndroidSnapshotHelper(options: {
     adb: AndroidAdbExecutor;
+    adbProvider?: AndroidAdbProvider | AndroidAdbExecutor;
     artifact: AndroidSnapshotHelperArtifact;
     deviceKey?: string;
     installPolicy?: AndroidSnapshotHelperInstallPolicy;
     timeoutMs?: number;
 }): Promise<AndroidSnapshotHelperInstallResult>;
 
+declare type ExecOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    allowFailure?: boolean;
+    binaryStdout?: boolean;
+    stdin?: string | Buffer;
+    timeoutMs?: number;
+    detached?: boolean;
+    signal?: AbortSignal;
+};
+
+declare type ExecResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    stdoutBuffer?: Buffer;
+};
+
 export declare function parseAndroidSnapshotHelperManifest(value: unknown): AndroidSnapshotHelperManifest;
 
 export declare function parseAndroidSnapshotHelperOutput(output: string): AndroidSnapshotHelperOutput;