appium-adb 16.1.2 → 16.2.0

package/lib/tools/lockmgmt.ts

@@ -41,6 +41,7 @@ export async function verifyLockCredential(this: ADB, credential: string | null
   try {
     const {stdout, stderr} = await this.shell(buildCommand('verify', credential), {
       outputFormat: this.EXEC_OUTPUT_FORMAT.FULL,
+      quoteArgs: true,
     });
     if (stdout?.includes('verified successfully')) {
       return true;
@@ -78,6 +79,7 @@ export async function clearLockCredential(this: ADB, credential: string | null =
   try {
     const {stdout, stderr} = await this.shell(buildCommand('clear', credential), {
       outputFormat: this.EXEC_OUTPUT_FORMAT.FULL,
+      quoteArgs: true,
     });
     if (!['user has no password', 'Lock credential cleared'].some((x) => (stderr || stdout)?.includes(x))) {
       throw new Error(stderr || stdout);
@@ -106,6 +108,7 @@ export async function isLockEnabled(this: ADB): Promise<boolean> {
   try {
     const {stdout, stderr} = await this.shell(buildCommand('get-disabled'), {
       outputFormat: this.EXEC_OUTPUT_FORMAT.FULL,
+      quoteArgs: true,
     });
     if (
       /\bfalse\b/.test(stdout) ||
@@ -160,6 +163,7 @@ export async function setLockCredential(
   try {
     const {stdout, stderr} = await this.shell(cmd, {
       outputFormat: this.EXEC_OUTPUT_FORMAT.FULL,
+      quoteArgs: true,
     });
     if (!stdout?.includes('set to')) {
       throw new Error(stderr || stdout);
@@ -318,10 +322,10 @@ export function isScreenOnFully(dumpsys: string): boolean {
 function buildCommand(verb: string, oldCredential: string | null = null, ...args: string[]): string[] {
   const cmd = ['locksettings', verb];
   if (oldCredential && !util.isEmpty(oldCredential)) {
-    cmd.push('--old', util.quote(`${oldCredential}`));
+    cmd.push('--old', `${oldCredential}`);
   }
   if (args.length > 0) {
-    cmd.push(...args.map((arg) => util.quote(`${arg}`)));
+    cmd.push(...args.map((arg) => `${arg}`));
   }
   return cmd;
 }

package/lib/tools/system-calls.ts

@@ -465,7 +465,12 @@ export const EXEC_OUTPUT_FORMAT = {
 } as const;
 
 /**
- * Execute the given adb command.
+ * Execute the given adb command without automatically quoting its arguments.
+ *
+ * When invoking `adb shell`, the device shell interprets the command.
+ * Unquoted values may be expanded or interpreted as shell syntax.
+ * For literal shell arguments, prefer `shell(args, {quoteArgs: true})`
+ * and pass unquoted argument values. `adbExec` itself does not apply `quoteArgs`.
  *
  * @param cmd - Command string or array of command arguments
  * @param opts - Execution options with `outputFormat: 'full'`
@@ -478,7 +483,12 @@ export async function adbExec(
   opts: AdbExecOptions & {outputFormat: 'full'},
 ): Promise<ExecResult>;
 /**
- * Execute the given adb command.
+ * Execute the given adb command without automatically quoting its arguments.
+ *
+ * When invoking `adb shell`, the device shell interprets the command.
+ * Unquoted values may be expanded or interpreted as shell syntax.
+ * For literal shell arguments, prefer `shell(args, {quoteArgs: true})`
+ * and pass unquoted argument values. `adbExec` itself does not apply `quoteArgs`.
  *
  * @param cmd - Command string or array of command arguments
  * @param opts - Execution options
@@ -593,9 +603,10 @@ export async function shell(
  */
 export async function shell(this: ADB, cmd: string | string[], opts?: ShellExecOptions): Promise<string>;
 export async function shell(this: ADB, cmd: string | string[], opts?: ShellExecOptions): Promise<string | ExecResult> {
-  const {privileged} = opts ?? {};
-
-  const cmdArr = Array.isArray(cmd) ? cmd : [cmd];
+  const {quoteArgs = false, ...execOpts} = opts ?? {};
+  const {privileged} = execOpts;
+  const args = Array.isArray(cmd) ? cmd : [cmd];
+  const cmdArr = quoteArgs ? args.map((arg) => util.quote(arg)) : args;
   const fullCmd: string[] = ['shell'];
   if (privileged) {
     log.info(`'adb shell ${util.quote(redactSecrets(cmdArr))}' requires root access`);
@@ -608,7 +619,7 @@ export async function shell(this: ADB, cmd: string | string[], opts?: ShellExecO
   } else {
     fullCmd.push(...cmdArr);
   }
-  return await this.adbExec(fullCmd, opts);
+  return await this.adbExec(fullCmd, opts === undefined ? undefined : execOpts);
 }
 
 /**
@@ -1368,16 +1379,25 @@ export async function isMitmCertificateInstalled(this: ADB, cert: Buffer | strin
  *
  * @param argTransformer - Function to transform each argument into command array
  * @param args - Array of arguments to process
+ * @param opts - Set quoteArgs to true for unquoted literal command arguments (default false)
  * @throws {Error} If argument transformer returns invalid result or command execution fails
  */
-export async function shellChunks(this: ADB, argTransformer: (x: string) => string[], args: string[]): Promise<void> {
+export async function shellChunks(
+  this: ADB,
+  argTransformer: (x: string) => string[],
+  args: string[],
+  opts: Pick<ShellExecOptions, 'quoteArgs'> = {},
+): Promise<void> {
   const commands: string[][] = [];
   let cmdChunk: string[] = [];
   for (const arg of args) {
-    const nextCmd = argTransformer(arg);
-    if (!Array.isArray(nextCmd)) {
+    const command = argTransformer(arg);
+    if (!Array.isArray(command)) {
       throw new Error('Argument transformer must result in an array');
     }
+    // Quote before measuring chunks and adding separators. A caller-supplied
+    // semicolon is literal data when quoting is enabled.
+    const nextCmd = opts.quoteArgs ? command.map((value) => util.quote(value)) : command;
     if (nextCmd.at(-1) !== ';') {
       nextCmd.push(';');
     }

package/lib/tools/types.ts

@@ -637,6 +637,14 @@ export interface SpecialAdbExecOptions {
 }
 
 export interface ShellExecOptions {
+  /**
+   * Quote each command argument as literal data for the device shell.
+   * Pass unquoted arguments when enabled. A string command is treated as one
+   * literal argument; use an array for an executable and its arguments.
+   * Defaults to false for compatibility with existing shell expressions.
+   * TODO: Enable by default in the next breaking release.
+   */
+  quoteArgs?: boolean;
   /**
    * The name of the corresponding Appium's timeout capability
    * (used in the error messages).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-adb",
-  "version": "16.1.2",
+  "version": "16.2.0",
   "description": "Android Debug Bridge interface",
   "homepage": "https://appium.io",
   "bugs": {
@@ -63,6 +63,5 @@
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
     "npm": ">=10"
-  },
-  "gitHead": "dd7fac6576be570d54de8ff2874b88426b4446dd"
+  }
 }