@yume-chan/android-bin 0.0.22 → 0.0.24

package/src/dumpsys.ts

@@ -1,5 +1,36 @@
 import { AdbCommandBase } from "@yume-chan/adb";
 
+const BatteryDumpFields: Record<
+    string,
+    {
+        type: "number" | "boolean" | "string";
+        field: keyof DumpSys.Battery.Info;
+    }
+> = {
+    "AC powered": { type: "boolean", field: "acPowered" },
+    "USB powered": { type: "boolean", field: "usbPowered" },
+    "Wireless powered": { type: "boolean", field: "wirelessPowered" },
+    "Dock powered": { type: "boolean", field: "dockPowered" },
+    "Max charging current": {
+        type: "number",
+        field: "maxChargingCurrent",
+    },
+    "Max charging voltage": {
+        type: "number",
+        field: "maxChargingVoltage",
+    },
+    "Charge counter": { type: "number", field: "chargeCounter" },
+    status: { type: "number", field: "status" },
+    health: { type: "number", field: "health" },
+    present: { type: "boolean", field: "present" },
+    level: { type: "number", field: "level" },
+    scale: { type: "number", field: "scale" },
+    voltage: { type: "number", field: "voltage" },
+    temperature: { type: "number", field: "temperature" },
+    technology: { type: "string", field: "technology" },
+    current: { type: "number", field: "current" },
+};
+
 export class DumpSys extends AdbCommandBase {
     async diskStats() {
         const output = await this.adb.subprocess.spawnAndWaitLegacy([
@@ -40,74 +71,67 @@ export class DumpSys extends AdbCommandBase {
             "battery",
         ]);
 
-        let acPowered = false;
-        let usbPowered = false;
-        let wirelessPowered = false;
-        let level: number | undefined;
-        let scale: number | undefined;
-        let voltage: number | undefined;
-        let current: number | undefined;
-        let status: DumpSys.Battery.Status | undefined;
-        let health: DumpSys.Battery.Health | undefined;
+        const info: DumpSys.Battery.Info = {
+            acPowered: false,
+            usbPowered: false,
+            wirelessPowered: false,
+            dockPowered: false,
+            status: DumpSys.Battery.Status.Unknown,
+            health: DumpSys.Battery.Health.Unknown,
+        };
+
         for (const line of output.split("\n")) {
-            const parts = line.split(":");
+            const parts = line.split(":").map((part) => part.trim());
             if (parts.length !== 2) {
                 continue;
             }
 
-            switch (parts[0]!.trim()) {
-                case "AC powered":
-                    acPowered = parts[1]!.trim() === "true";
-                    break;
-                case "USB powered":
-                    usbPowered = parts[1]!.trim() === "true";
-                    break;
-                case "Wireless powered":
-                    wirelessPowered = parts[1]!.trim() === "true";
-                    break;
-                case "level":
-                    level = Number.parseInt(parts[1]!.trim(), 10);
-                    break;
-                case "scale":
-                    scale = Number.parseInt(parts[1]!.trim(), 10);
-                    break;
-                case "voltage":
-                    voltage = Number.parseInt(parts[1]!.trim(), 10);
-                    break;
-                case "current now":
-                    current = Number.parseInt(parts[1]!.trim(), 10);
+            const field = BatteryDumpFields[parts[0]!];
+            if (!field) {
+                continue;
+            }
+
+            switch (field.type) {
+                case "boolean":
+                    info[field.field] = (parts[1]!.trim() === "true") as never;
                     break;
-                case "status":
-                    status = Number.parseInt(
+                case "number":
+                    info[field.field] = Number.parseInt(
                         parts[1]!.trim(),
                         10,
-                    ) as DumpSys.Battery.Status;
+                    ) as never;
                     break;
-                case "health":
-                    health = Number.parseInt(
-                        parts[1]!.trim(),
-                        10,
-                    ) as DumpSys.Battery.Health;
+                case "string":
+                    info[field.field] = parts[1]! as never;
                     break;
             }
         }
 
-        return {
-            acPowered,
-            usbPowered,
-            wirelessPowered,
-            level,
-            scale,
-            voltage,
-            current,
-            status,
-            health,
-        };
+        return info;
     }
 }
 
 export namespace DumpSys {
     export namespace Battery {
+        export interface Info {
+            acPowered: boolean;
+            usbPowered: boolean;
+            wirelessPowered: boolean;
+            dockPowered: boolean;
+            maxChargingCurrent?: number;
+            maxChargingVoltage?: number;
+            chargeCounter?: number;
+            status: Status;
+            health: Health;
+            present?: boolean;
+            level?: number;
+            scale?: number;
+            voltage?: number;
+            temperature?: number;
+            technology?: string;
+            current?: number;
+        }
+
         export enum Status {
             Unknown = 1,
             Charging,

package/src/logcat.ts

@@ -5,8 +5,8 @@ import { AdbCommandBase, AdbSubprocessNoneProtocol } from "@yume-chan/adb";
 import type { ReadableStream } from "@yume-chan/stream-extra";
 import {
     BufferedTransformStream,
-    DecodeUtf8Stream,
     SplitStringStream,
+    TextDecoderStream,
     WrapReadableStream,
     WritableStream,
 } from "@yume-chan/stream-extra";
@@ -353,6 +353,7 @@ export async function deserializeAndroidLogEntry(
 ): Promise<AndroidLogEntry> {
     const entry = (await LoggerEntry.deserialize(stream)) as AndroidLogEntry;
     if (entry.headerSize !== LoggerEntry.size) {
+        // Skip unknown fields
         await stream.readExactly(entry.headerSize - LoggerEntry.size);
     }
 
@@ -384,7 +385,7 @@ export interface LogSize {
 
 export class Logcat extends AdbCommandBase {
     static logIdToName(id: LogId): string {
-        return LogId[id]!;
+        return LogId[id];
     }
 
     static logNameToId(name: string): LogId {
@@ -420,7 +421,7 @@ export class Logcat extends AdbCommandBase {
 
         const result: LogSize[] = [];
         await stdout
-            .pipeThrough(new DecodeUtf8Stream())
+            .pipeThrough(new TextDecoderStream())
             .pipeThrough(new SplitStringStream("\n"))
             .pipeTo(
                 new WritableStream({

package/src/pm.ts

@@ -4,16 +4,12 @@
 // cspell:ignore versioncode
 
 import type { Adb } from "@yume-chan/adb";
-import {
-    AdbCommandBase,
-    AdbSubprocessNoneProtocol,
-    escapeArg,
-} from "@yume-chan/adb";
-import type { Consumable, ReadableStream } from "@yume-chan/stream-extra";
+import { AdbCommandBase, escapeArg } from "@yume-chan/adb";
+import type { MaybeConsumable, ReadableStream } from "@yume-chan/stream-extra";
 import {
     ConcatStringStream,
-    DecodeUtf8Stream,
     SplitStringStream,
+    TextDecoderStream,
 } from "@yume-chan/stream-extra";
 
 import { Cmd } from "./cmd.js";
@@ -230,6 +226,11 @@ export interface PackageManagerUninstallOptions {
     keepData: boolean;
     user: SingleUserOrAll;
     versionCode: number;
+    /**
+     * Only remove the specified splits, not the entire app
+     *
+     * On Android 10 and lower, only one split name can be specified.
+     */
     splitNames: string[];
 }
 
@@ -263,27 +264,48 @@ export class PackageManager extends AdbCommandBase {
     }
 
     #buildInstallArguments(
+        command: string,
         options: Partial<PackageManagerInstallOptions> | undefined,
     ): string[] {
-        return buildArguments(
-            ["pm", "install"],
+        const args = buildArguments(
+            ["pm", command],
             options,
             PACKAGE_MANAGER_INSTALL_OPTIONS_MAP,
         );
+        if (!options?.skipExisting) {
+            /*
+             * | behavior             | previous version     | modern version       |
+             * | -------------------- | -------------------- | -------------------- |
+             * | replace existing app | requires `-r`        | default behavior [1] |
+             * | skip existing app    | default behavior [2] | requires `-R`        |
+             *
+             * [1]: `-r` recognized but ignored)
+             * [2]: `-R` not recognized but ignored
+             *
+             * So add `-r` when `skipExisting` is `false` for compatibility.
+             */
+            args.push("-r");
+        }
+        return args;
     }
 
+    /**
+     * Install the apk file.
+     *
+     * @param apks Path to the apk file. It must exist on the device. On Android 10 and lower, only one apk can be specified.
+     */
     async install(
         apks: string[],
         options?: Partial<PackageManagerInstallOptions>,
     ): Promise<string> {
-        const args = this.#buildInstallArguments(options);
+        const args = this.#buildInstallArguments("install", options);
         // WIP: old version of pm doesn't support multiple apks
         args.push(...apks);
         return await this.adb.subprocess.spawnAndWaitLegacy(args);
     }
 
     async pushAndInstallStream(
-        stream: ReadableStream<Consumable<Uint8Array>>,
+        stream: ReadableStream<MaybeConsumable<Uint8Array>>,
         options?: Partial<PackageManagerInstallOptions>,
     ): Promise<void> {
         const sync = await this.adb.sync();
@@ -300,49 +322,55 @@ export class PackageManager extends AdbCommandBase {
             await sync.dispose();
         }
 
-        // Starting from Android 7, `pm` is only a wrapper for `cmd package`,
-        // and `cmd package` launches faster than `pm`.
-        // But `cmd package` can't read `/data/local/tmp` folder due to SELinux policy,
-        // so installing a file must use `pm`.
-        const args = this.#buildInstallArguments(options);
+        // Starting from Android 7, `pm` becomes a wrapper to `cmd package`.
+        // The benefit of `cmd package` is it starts faster than the old `pm`,
+        // because it connects to the already running `system` process,
+        // instead of initializing all system components from scratch.
+        //
+        // But launching `cmd package` directly causes it to not be able to
+        // read files in `/data/local/tmp` (and many other places) due to SELinux policies,
+        // so installing files must still use `pm`.
+        // (the starting executable file decides which SELinux policies to apply)
+        const args = this.#buildInstallArguments("install", options);
         args.push(filePath);
-        const process = await this.adb.subprocess.spawn(args.map(escapeArg), {
-            protocols: [AdbSubprocessNoneProtocol],
-        });
-
-        const output = await process.stdout
-            .pipeThrough(new DecodeUtf8Stream())
-            .pipeThrough(new ConcatStringStream())
-            .then((output) => output.trim());
 
-        await this.adb.rm(filePath);
+        try {
+            const output = await this.adb.subprocess
+                .spawnAndWaitLegacy(args.map(escapeArg))
+                .then((output) => output.trim());
 
-        if (output !== "Success") {
-            throw new Error(output);
+            if (output !== "Success") {
+                throw new Error(output);
+            }
+        } finally {
+            await this.adb.rm(filePath);
         }
     }
 
     async installStream(
         size: number,
-        stream: ReadableStream<Consumable<Uint8Array>>,
+        stream: ReadableStream<MaybeConsumable<Uint8Array>>,
         options?: Partial<PackageManagerInstallOptions>,
     ): Promise<void> {
         // Android 7 added both `cmd` command and streaming install support,
-        // we can't detect whether `pm` supports streaming install,
-        // so we detect `cmd` command support instead.
+        // It's hard to detect whether `pm` supports streaming install (unless actually trying),
+        // so check for whether `cmd` is supported,
+        // and assume `pm` streaming install support status is same as that.
         if (!this.#cmd.supportsCmd) {
+            // Fall back to push file then install
             await this.pushAndInstallStream(stream, options);
             return;
         }
 
-        const args = this.#buildInstallArguments(options);
-        // Remove `pm` from args, final command will starts with `cmd package install`
+        const args = this.#buildInstallArguments("install", options);
+        // Remove `pm` from args, `Cmd#spawn` will prepend `cmd <command>` so the final args
+        // will be `cmd package install <args>`
         args.shift();
         args.push("-S", size.toString());
         const process = await this.#cmd.spawn(false, "package", ...args);
 
         const output = process.stdout
-            .pipeThrough(new DecodeUtf8Stream())
+            .pipeThrough(new TextDecoderStream())
             .pipeThrough(new ConcatStringStream())
             .then((output) => output.trim());
 
@@ -356,8 +384,6 @@ export class PackageManager extends AdbCommandBase {
         ]);
     }
 
-    // TODO: install: support split apk formats (`adb install-multiple`)
-
     static parsePackageListItem(
         line: string,
     ): PackageManagerListPackagesResult {
@@ -369,7 +395,7 @@ export class PackageManager extends AdbCommandBase {
         let installer: string | undefined;
         let uid: number | undefined;
 
-        // Parse backwards
+        // The output format is easier to parse in backwards
         let index = line.indexOf(" uid:");
         if (index !== -1) {
             uid = Number.parseInt(line.substring(index + " uid:".length), 10);
@@ -391,7 +417,9 @@ export class PackageManager extends AdbCommandBase {
             line = line.substring(0, index);
         }
 
-        // `sourceDir` may contain `=` so use `lastIndexOf`
+        // `sourceDir` may contain `=` characters
+        // (because in newer Android versions it's a base64 string of encrypted package name),
+        // so use `lastIndexOf`
         index = line.lastIndexOf("=");
         if (index !== -1) {
             sourceDir = line.substring(0, index);
@@ -432,7 +460,10 @@ export class PackageManager extends AdbCommandBase {
 
         const process = await this.#cmdOrSubprocess(args);
         const reader = process.stdout
-            .pipeThrough(new DecodeUtf8Stream())
+            .pipeThrough(new TextDecoderStream())
+            // FIXME: `SplitStringStream` will throw away some data
+            // if it doesn't end with a separator. So each chunk of data
+            // must contain several complete lines.
             .pipeThrough(new SplitStringStream("\n"))
             .getReader();
         while (true) {
@@ -460,7 +491,7 @@ export class PackageManager extends AdbCommandBase {
 
         const process = await this.#cmdOrSubprocess(args);
         const output = await process.stdout
-            .pipeThrough(new DecodeUtf8Stream())
+            .pipeThrough(new TextDecoderStream())
             .pipeThrough(new ConcatStringStream())
             .then((output) => output.trim());
         if (output !== "Success") {
@@ -481,7 +512,7 @@ export class PackageManager extends AdbCommandBase {
 
         const process = await this.#cmdOrSubprocess(args);
         const output = await process.stdout
-            .pipeThrough(new DecodeUtf8Stream())
+            .pipeThrough(new TextDecoderStream())
             .pipeThrough(new ConcatStringStream())
             .then((output) => output.trim());
 
@@ -491,4 +522,147 @@ export class PackageManager extends AdbCommandBase {
 
         return output;
     }
+
+    /**
+     * Creates a new install session.
+     *
+     * Install sessions are used to install apps with multiple splits, but it can also be used to install a single apk.
+     *
+     * Install sessions was added in Android 5.0 (API level 21).
+     *
+     * @param options Options for the install session
+     * @returns ID of the new install session
+     */
+    async sessionCreate(options?: Partial<PackageManagerInstallOptions>) {
+        const args = this.#buildInstallArguments("install-create", options);
+
+        const process = await this.#cmdOrSubprocess(args);
+        const output = await process.stdout
+            .pipeThrough(new TextDecoderStream())
+            .pipeThrough(new ConcatStringStream())
+            .then((output) => output.trim());
+
+        const sessionIdString = output.match(/.*\[(\d+)\].*/);
+        if (!sessionIdString) {
+            throw new Error("Failed to create install session");
+        }
+
+        return Number.parseInt(sessionIdString[1]!, 10);
+    }
+
+    async sessionAddSplit(sessionId: number, splitName: string, path: string) {
+        const args: string[] = [
+            "pm",
+            "install-write",
+            sessionId.toString(),
+            splitName,
+            path,
+        ];
+
+        const output = await this.adb.subprocess
+            .spawnAndWaitLegacy(args)
+            .then((output) => output.trim());
+        if (!output.startsWith("Success")) {
+            throw new Error(output);
+        }
+    }
+
+    async sessionAddSplitStream(
+        sessionId: number,
+        splitName: string,
+        size: number,
+        stream: ReadableStream<MaybeConsumable<Uint8Array>>,
+    ) {
+        const args: string[] = [
+            "pm",
+            "install-write",
+            "-S",
+            size.toString(),
+            sessionId.toString(),
+            splitName,
+            "-",
+        ];
+
+        const process = await this.#cmdOrSubprocess(args);
+        const output = process.stdout
+            .pipeThrough(new TextDecoderStream())
+            .pipeThrough(new ConcatStringStream())
+            .then((output) => output.trim());
+
+        await Promise.all([
+            stream.pipeTo(process.stdin),
+            output.then((output) => {
+                if (!output.startsWith("Success")) {
+                    throw new Error(output);
+                }
+            }),
+        ]);
+    }
+
+    async sessionCommit(sessionId: number) {
+        const args: string[] = ["pm", "install-commit", sessionId.toString()];
+        const output = await this.adb.subprocess
+            .spawnAndWaitLegacy(args)
+            .then((output) => output.trim());
+        if (output !== "Success") {
+            throw new Error(output);
+        }
+    }
+
+    async sessionAbandon(sessionId: number) {
+        const args: string[] = ["pm", "install-abandon", sessionId.toString()];
+        const output = await this.adb.subprocess
+            .spawnAndWaitLegacy(args)
+            .then((output) => output.trim());
+        if (output !== "Success") {
+            throw new Error(output);
+        }
+    }
+}
+
+export class PackageManagerInstallSession {
+    static async create(
+        packageManager: PackageManager,
+        options?: Partial<PackageManagerInstallOptions>,
+    ) {
+        const id = await packageManager.sessionCreate(options);
+        return new PackageManagerInstallSession(packageManager, id);
+    }
+
+    #packageManager: PackageManager;
+
+    #id: number;
+    get id() {
+        return this.#id;
+    }
+
+    constructor(packageManager: PackageManager, id: number) {
+        this.#packageManager = packageManager;
+        this.#id = id;
+    }
+
+    addSplit(splitName: string, path: string) {
+        return this.#packageManager.sessionAddSplit(this.#id, splitName, path);
+    }
+
+    addSplitStream(
+        splitName: string,
+        size: number,
+        stream: ReadableStream<MaybeConsumable<Uint8Array>>,
+    ) {
+        return this.#packageManager.sessionAddSplitStream(
+            this.#id,
+            splitName,
+            size,
+            stream,
+        );
+    }
+
+    commit() {
+        return this.#packageManager.sessionCommit(this.#id);
+    }
+
+    abandon() {
+        return this.#packageManager.sessionAbandon(this.#id);
+    }
 }

package/src/string-format.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-argument */
 export class ParseError extends Error {
     #expected: string[];