@yume-chan/android-bin 2.0.1 → 3.0.0-beta.0

package/src/cmd/none.ts

@@ -0,0 +1,62 @@
+import type { Adb } from "@yume-chan/adb";
+import {
+    AdbFeature,
+    AdbNoneProtocolProcessImpl,
+    adbNoneProtocolSpawner,
+    escapeArg,
+} from "@yume-chan/adb";
+
+import { Cmd } from "./service.js";
+import { checkCommand, resolveFallback, serializeAbbService } from "./utils.js";
+
+export function createNoneProtocol(
+    adb: Adb,
+    fallback: NonNullable<Cmd.Fallback>,
+): Cmd.NoneProtocolService;
+export function createNoneProtocol(
+    adb: Adb,
+    fallback?: Cmd.Fallback,
+): Cmd.NoneProtocolService | undefined;
+export function createNoneProtocol(
+    adb: Adb,
+    fallback?: Cmd.Fallback,
+): Cmd.NoneProtocolService | undefined {
+    if (adb.canUseFeature(AdbFeature.AbbExec)) {
+        return {
+            mode: Cmd.Mode.Abb,
+            spawn: adbNoneProtocolSpawner(async (command, signal) => {
+                const service = serializeAbbService("abb_exec", command);
+                const socket = await adb.createSocket(service);
+                return new AdbNoneProtocolProcessImpl(socket, signal);
+            }),
+        };
+    }
+
+    if (adb.canUseFeature(AdbFeature.Cmd)) {
+        return {
+            mode: Cmd.Mode.Cmd,
+            spawn: adbNoneProtocolSpawner(async (command, signal) => {
+                checkCommand(command);
+
+                const newCommand = command.map(escapeArg);
+                newCommand.unshift("cmd");
+                return adb.subprocess.noneProtocol.spawn(newCommand, signal);
+            }),
+        };
+    }
+
+    if (fallback) {
+        return {
+            mode: Cmd.Mode.Fallback,
+            spawn: adbNoneProtocolSpawner(async (command, signal) => {
+                checkCommand(command);
+
+                const newCommand = command.map(escapeArg);
+                newCommand[0] = resolveFallback(fallback, command[0]!);
+                return adb.subprocess.noneProtocol.spawn(newCommand, signal);
+            }),
+        };
+    }
+
+    return undefined;
+}

package/src/cmd/service.ts

@@ -0,0 +1,54 @@
+import type {
+    Adb,
+    AdbNoneProtocolSpawner,
+    AdbShellProtocolSpawner,
+} from "@yume-chan/adb";
+
+import { createNoneProtocol } from "./none.js";
+import { createShellProtocol } from "./shell.js";
+
+export class Cmd {
+    static readonly Mode = {
+        Abb: 0,
+        Cmd: 1,
+        Fallback: 2,
+    } as const;
+
+    static readonly createNoneProtocol = createNoneProtocol;
+    static readonly createShellProtocol = createShellProtocol;
+
+    #noneProtocol: Cmd.NoneProtocolService | undefined;
+    get noneProtocol() {
+        return this.#noneProtocol;
+    }
+
+    #shellProtocol: Cmd.ShellProtocolService | undefined;
+    get shellProtocol() {
+        return this.#shellProtocol;
+    }
+
+    constructor(adb: Adb, fallback?: Cmd.Fallback) {
+        this.#noneProtocol = createNoneProtocol(adb, fallback);
+        this.#shellProtocol = createShellProtocol(adb, fallback);
+    }
+}
+
+export namespace Cmd {
+    export type Fallback =
+        | string
+        | Record<string, string>
+        | ((service: string) => string)
+        | undefined;
+
+    export type Mode = (typeof Cmd.Mode)[keyof typeof Cmd.Mode];
+
+    export interface NoneProtocolService {
+        mode: Mode;
+        spawn: AdbNoneProtocolSpawner;
+    }
+
+    export interface ShellProtocolService {
+        mode: Mode;
+        spawn: AdbShellProtocolSpawner;
+    }
+}

package/src/cmd/shell.ts

@@ -0,0 +1,67 @@
+import type { Adb } from "@yume-chan/adb";
+import {
+    AdbFeature,
+    AdbShellProtocolProcessImpl,
+    adbShellProtocolSpawner,
+    escapeArg,
+} from "@yume-chan/adb";
+
+import { Cmd } from "./service.js";
+import { checkCommand, resolveFallback, serializeAbbService } from "./utils.js";
+
+export function createShellProtocol(
+    adb: Adb,
+    fallback: NonNullable<Cmd.Fallback>,
+): Cmd.ShellProtocolService;
+export function createShellProtocol(
+    adb: Adb,
+    fallback?: Cmd.Fallback,
+): Cmd.ShellProtocolService | undefined;
+export function createShellProtocol(
+    adb: Adb,
+    fallback?: Cmd.Fallback,
+): Cmd.ShellProtocolService | undefined {
+    if (adb.canUseFeature(AdbFeature.Abb)) {
+        return {
+            mode: Cmd.Mode.Abb,
+            spawn: adbShellProtocolSpawner(async (command, signal) => {
+                const service = serializeAbbService("abb", command);
+                const socket = await adb.createSocket(service);
+                return new AdbShellProtocolProcessImpl(socket, signal);
+            }),
+        };
+    }
+
+    const shellProtocolService = adb.subprocess.shellProtocol;
+    if (!shellProtocolService) {
+        return undefined;
+    }
+
+    if (adb.canUseFeature(AdbFeature.Cmd)) {
+        return {
+            mode: Cmd.Mode.Cmd,
+            spawn: adbShellProtocolSpawner(async (command, signal) => {
+                checkCommand(command);
+
+                const newCommand = command.map(escapeArg);
+                newCommand.unshift("cmd");
+                return shellProtocolService.spawn(newCommand, signal);
+            }),
+        };
+    }
+
+    if (fallback) {
+        return {
+            mode: Cmd.Mode.Fallback,
+            spawn: adbShellProtocolSpawner(async (command, signal) => {
+                checkCommand(command);
+
+                const newCommand = command.map(escapeArg);
+                newCommand[0] = resolveFallback(fallback, command[0]!);
+                return shellProtocolService.spawn(newCommand, signal);
+            }),
+        };
+    }
+
+    return undefined;
+}

package/src/cmd/utils.ts

@@ -0,0 +1,35 @@
+import type { Cmd } from "./service.js";
+
+export function resolveFallback(
+    fallback: Cmd.Fallback,
+    command: string,
+): string {
+    if (typeof fallback === "function") {
+        fallback = fallback(command);
+    } else if (typeof fallback === "object" && fallback !== null) {
+        fallback = fallback[command];
+    }
+
+    if (!fallback) {
+        throw new Error(`No fallback configured for command "${command}"`);
+    }
+
+    return fallback;
+}
+
+export function checkCommand(command: readonly string[]) {
+    if (!command.length) {
+        throw new TypeError("Command is empty");
+    }
+}
+
+export function serializeAbbService(
+    prefix: string,
+    command: readonly string[],
+): string {
+    checkCommand(command);
+
+    // `abb` mode uses `\0` as the separator, allowing space in arguments.
+    // The last `\0` is required for older versions of `adb`.
+    return `${prefix}:${command.join("\0")}\0`;
+}

package/src/demo-mode.ts

@@ -5,8 +5,8 @@
 // cspell: ignore sysui
 
 import type { Adb } from "@yume-chan/adb";
-import { AdbServiceBase } from "@yume-chan/adb";
 
+import { ActivityManager } from "./am.js";
 import { Settings } from "./settings.js";
 
 export enum DemoModeSignalStrength {
@@ -51,11 +51,12 @@ export const DemoModeStatusBarModes = [
 
 export type DemoModeStatusBarMode = (typeof DemoModeStatusBarModes)[number];
 
-export class DemoMode extends AdbServiceBase {
+export class DemoMode {
+    #am: ActivityManager;
     #settings: Settings;
 
-    constructor(adb: Adb) {
-        super(adb);
+    constructor(adb: Adb, apiLevel?: number) {
+        this.#am = new ActivityManager(adb, apiLevel);
         this.#settings = new Settings(adb);
     }
 
@@ -108,26 +109,14 @@ export class DemoMode extends AdbServiceBase {
         }
     }
 
-    async broadcast(
-        command: string,
-        extra?: Record<string, string>,
-    ): Promise<void> {
-        await this.adb.subprocess.noneProtocol.spawnWaitText([
-            "am",
-            "broadcast",
-            "-a",
-            "com.android.systemui.demo",
-            "-e",
-            "command",
-            command,
-            ...(extra
-                ? Object.entries(extra).flatMap(([key, value]) => [
-                      "-e",
-                      key,
-                      value,
-                  ])
-                : []),
-        ]);
+    broadcast(command: string, extras?: Record<string, string>): Promise<void> {
+        return this.#am.broadcast({
+            action: "com.android.systemui.demo",
+            extras: {
+                command,
+                ...extras,
+            },
+        });
     }
 
     async setBatteryLevel(level: number): Promise<void> {

package/src/dumpsys.ts

@@ -1,4 +1,4 @@
-import { AdbServiceBase } from "@yume-chan/adb";
+import type { Adb } from "@yume-chan/adb";
 
 const BatteryDumpFields: Record<
     string,
@@ -54,14 +54,20 @@ const Battery = {
     Health,
 };
 
-export class DumpSys extends AdbServiceBase {
+export class DumpSys {
     static readonly Battery = Battery;
 
+    readonly #adb: Adb;
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
+
     async diskStats() {
-        const result = await this.adb.subprocess.noneProtocol.spawnWaitText([
-            "dumpsys",
-            "diskstats",
-        ]);
+        const result = await this.#adb.subprocess.noneProtocol
+            .spawn(["dumpsys", "diskstats"])
+            .wait()
+            .toString();
 
         function getSize(name: string) {
             const match = result.match(
@@ -91,10 +97,10 @@ export class DumpSys extends AdbServiceBase {
     }
 
     async battery(): Promise<DumpSys.Battery.Info> {
-        const result = await this.adb.subprocess.noneProtocol.spawnWaitText([
-            "dumpsys",
-            "battery",
-        ]);
+        const result = await this.#adb.subprocess.noneProtocol
+            .spawn(["dumpsys", "battery"])
+            .wait()
+            .toString();
 
         const info: DumpSys.Battery.Info = {
             acPowered: false,

package/src/index.ts

@@ -3,7 +3,7 @@
 export * from "./am.js";
 export * from "./bu.js";
 export * from "./bug-report.js";
-export * from "./cmd.js";
+export * from "./cmd/index.js";
 export * from "./demo-mode.js";
 export * from "./dumpsys.js";
 export * from "./intent.js";

package/src/intent.ts

@@ -1,73 +1,211 @@
-export class IntentBuilder {
-    #action: string | undefined;
-    #categories: string[] = [];
-    #packageName: string | undefined;
-    #component: string | undefined;
-    #data: string | undefined;
-    #type: string | undefined;
-    #stringExtras = new Map<string, string>();
-
-    setAction(action: string): this {
-        this.#action = action;
-        return this;
-    }
+// cspell: ignore eial
+// cspell: ignore elal
+// cspell: ignore efal
+// cspell: ignore esal
+// cspell: ignore edal
+
+export interface ComponentName {
+    packageName: string;
+    className: string;
+}
+
+export interface Intent {
+    action?: string | undefined;
+    data?: string | undefined;
+    type?: string | undefined;
+    identifier?: string | undefined;
+    categories?: string[] | undefined;
+    extras?:
+        | Record<
+              string,
+              | string
+              | null
+              | number
+              | bigint
+              | Intent.Extra.String
+              | ComponentName
+              | Intent.Extra.NumberArray
+              | Intent.Extra.StringArray
+              | Intent.Extra.Number
+              | boolean
+          >
+        | undefined;
+    flags?: number | undefined;
+    package?: string | undefined;
+    component?: ComponentName | undefined;
+}
+
+export namespace Intent {
+    export namespace Extra {
+        export interface Number {
+            type: "long" | "float" | "double";
+            value: number;
+        }
 
-    addCategory(category: string): this {
-        this.#categories.push(category);
-        return this;
+        export interface String {
+            type: "uri";
+            value: string;
+        }
+
+        export interface NumberArray {
+            type: "array" | "arrayList";
+            itemType: "int" | Number["type"];
+            value: number[];
+        }
+
+        export interface StringArray {
+            type: "array" | "arrayList";
+            itemType: "string";
+            value: string[];
+        }
     }
+}
 
-    setPackage(packageName: string): this {
-        this.#packageName = packageName;
-        return this;
+function getNumberType(type: "int" | Intent.Extra.Number["type"]) {
+    switch (type) {
+        case "int":
+            return "--ei";
+        case "long":
+            return "--el";
+        case "float":
+            return "--ef";
+        case "double":
+            return "--ed";
+        default:
+            throw new Error(`Unknown number type: ${type as string}`);
     }
+}
 
-    setComponent(component: string): this {
-        this.#component = component;
-        return this;
+function serializeExtraArray(
+    array: Intent.Extra.NumberArray | Intent.Extra.StringArray,
+): [type: string, value: string] {
+    let type: string;
+    let value: string;
+
+    if (array.itemType === "string") {
+        type = "--es";
+        value = array.value
+            .map((item) => item.replaceAll(",", "\\,"))
+            .join(",");
+    } else {
+        type = getNumberType(array.itemType);
+        value = array.value.join(",");
     }
 
-    setData(data: string): this {
-        this.#data = data;
-        return this;
+    if (array.type === "array") {
+        type += "a";
+    } else {
+        type += "al";
     }
 
-    addStringExtra(key: string, value: string): this {
-        this.#stringExtras.set(key, value);
-        return this;
+    return [type, value];
+}
+
+function serializeString(
+    result: string[],
+    key: string,
+    value: string | undefined,
+) {
+    // Treat empty string as not set
+    if (value) {
+        result.push(key, value);
     }
+}
 
-    build(): string[] {
-        const result: string[] = [];
+export function serializeIntent(intent: Intent) {
+    const result: string[] = [];
 
-        if (this.#action) {
-            result.push("-a", this.#action);
-        }
+    serializeString(result, "-a", intent.action);
+    serializeString(result, "-d", intent.data);
+    serializeString(result, "-t", intent.type);
+    serializeString(result, "-i", intent.identifier);
 
-        for (const category of this.#categories) {
+    if (intent.categories) {
+        for (const category of intent.categories) {
             result.push("-c", category);
         }
+    }
 
-        if (this.#packageName) {
-            result.push("-p", this.#packageName);
-        }
+    if (intent.extras) {
+        for (const [key, value] of Object.entries(intent.extras)) {
+            switch (typeof value) {
+                case "string":
+                    result.push("--es", key, value);
+                    break;
+                case "object":
+                    if (value === null) {
+                        result.push("--esn", key);
+                        break;
+                    }
 
-        if (this.#component) {
-            result.push("-n", this.#component);
-        }
+                    // `ComponentName`
+                    if ("packageName" in value) {
+                        result.push(
+                            "--ecn",
+                            key,
+                            value.packageName + "/" + value.className,
+                        );
+                        break;
+                    }
 
-        if (this.#data) {
-            result.push("-d", this.#data);
+                    switch (value.type) {
+                        case "uri":
+                            result.push("--eu", key, value.value);
+                            break;
+                        case "array":
+                        case "arrayList":
+                            {
+                                const [type, valueString] =
+                                    serializeExtraArray(value);
+                                result.push(type, key, valueString);
+                            }
+                            break;
+                        default:
+                            result.push(
+                                getNumberType(value.type),
+                                key,
+                                value.value.toString(),
+                            );
+                            break;
+                    }
+                    break;
+                case "number":
+                    if (value % 1 !== 0) {
+                        throw new Error(
+                            `Extra \`${key}\` is not an integer, must use \`Intent.Extra.Number\` type instead`,
+                        );
+                    }
+                    // Infer type from value
+                    if (value < -2147483648 || value > 2147483647) {
+                        result.push("--el", key, value.toString());
+                    } else {
+                        result.push("--ei", key, value.toString());
+                    }
+                    break;
+                case "bigint":
+                    result.push("--el", key, value.toString());
+                    break;
+                case "boolean":
+                    result.push("--ez", key, value ? "true" : "false");
+                    break;
+            }
         }
+    }
 
-        if (this.#type) {
-            result.push("-t", this.#type);
-        }
+    if (intent.component) {
+        result.push(
+            "-n",
+            intent.component.packageName + "/" + intent.component.className,
+        );
+    }
 
-        for (const [key, value] of this.#stringExtras) {
-            result.push("--es", key, value);
-        }
+    serializeString(result, "-p", intent.package);
 
-        return result;
+    // `0` is the default value for `flags` when deserializing
+    // so it can be omitted if it's either `undefined` or `0`
+    if (intent.flags) {
+        result.push("-f", intent.flags.toString());
     }
+
+    return result;
 }

package/src/logcat.ts

@@ -1,7 +1,7 @@
 // cspell: ignore logcat
 // cspell: ignore usec
 
-import { AdbServiceBase } from "@yume-chan/adb";
+import type { Adb } from "@yume-chan/adb";
 import type { ReadableStream } from "@yume-chan/stream-extra";
 import {
     BufferedTransformStream,
@@ -90,7 +90,7 @@ export interface LogcatFormatModifiers {
 export interface LogcatOptions {
     dump?: boolean | undefined;
     pid?: number | undefined;
-    ids?: LogId[] | undefined;
+    ids?: readonly LogId[] | undefined;
     tail?: number | Date | undefined;
 }
 
@@ -405,7 +405,7 @@ export interface LogSize {
     maxPayloadSize: number;
 }
 
-export class Logcat extends AdbServiceBase {
+export class Logcat {
     static logIdToName(id: LogId): string {
         return LogIdName[id]!;
     }
@@ -415,7 +415,7 @@ export class Logcat extends AdbServiceBase {
         return LogId[key as keyof typeof LogId];
     }
 
-    static joinLogId(ids: LogId[]): string {
+    static joinLogId(ids: readonly LogId[]): string {
         return ids.map((id) => Logcat.logIdToName(id)).join(",");
     }
 
@@ -434,8 +434,14 @@ export class Logcat extends AdbServiceBase {
     static readonly LOG_SIZE_REGEX_11: RegExp =
         /(.*): ring buffer is (.*) (.*)B \((.*) (.*)B consumed, (.*) (.*)B readable\), max entry is (.*) B, max payload is (.*) B/;
 
-    async getLogSize(ids?: LogId[]): Promise<LogSize[]> {
-        const process = await this.adb.subprocess.noneProtocol.spawn([
+    readonly #adb: Adb;
+
+    constructor(adb: Adb) {
+        this.#adb = adb;
+    }
+
+    async getLogSize(ids?: readonly LogId[]): Promise<LogSize[]> {
+        const process = await this.#adb.subprocess.noneProtocol.spawn([
             "logcat",
             "-g",
             ...(ids ? ["-b", Logcat.joinLogId(ids)] : []),
@@ -444,7 +450,7 @@ export class Logcat extends AdbServiceBase {
         const result: LogSize[] = [];
         for await (const line of process.output
             .pipeThrough(new TextDecoderStream())
-            .pipeThrough(new SplitStringStream("\n"))) {
+            .pipeThrough(new SplitStringStream("\n", { trim: true }))) {
             let match = line.match(Logcat.LOG_SIZE_REGEX_11);
             if (match) {
                 result.push({
@@ -488,13 +494,13 @@ export class Logcat extends AdbServiceBase {
         return result;
     }
 
-    async clear(ids?: LogId[]): Promise<void> {
+    async clear(ids?: readonly LogId[]): Promise<void> {
         const args = ["logcat", "-c"];
         if (ids && ids.length > 0) {
             args.push("-b", Logcat.joinLogId(ids));
         }
 
-        await this.adb.subprocess.noneProtocol.spawnWaitText(args);
+        await this.#adb.subprocess.noneProtocol.spawn(args).wait();
     }
 
     binary(options?: LogcatOptions): ReadableStream<AndroidLogEntry> {
@@ -520,7 +526,7 @@ export class Logcat extends AdbServiceBase {
 
             // TODO: make `spawn` return synchronously with streams pending
             // so it's easier to chain them.
-            const process = await this.adb.subprocess.noneProtocol.spawn(args);
+            const process = await this.#adb.subprocess.noneProtocol.spawn(args);
             return process.output;
         }).pipeThrough(
             new BufferedTransformStream((stream) => {