@yume-chan/android-bin 0.0.20 → 0.0.21

package/src/bug-report.ts

@@ -1,9 +1,11 @@
 // cspell: ignore bugreport
 // cspell: ignore bugreportz
 
+import type { Adb, AdbSync } from "@yume-chan/adb";
 import { AdbCommandBase, AdbSubprocessShellProtocol } from "@yume-chan/adb";
-import type { ReadableStream } from "@yume-chan/stream-extra";
+import type { AbortSignal, ReadableStream } from "@yume-chan/stream-extra";
 import {
+    AbortController,
     DecodeUtf8Stream,
     PushReadableStream,
     SplitStringStream,
@@ -11,80 +13,200 @@ import {
     WritableStream,
 } from "@yume-chan/stream-extra";
 
-export interface BugReportZVersion {
-    major: number;
-    minor: number;
+export interface BugReportCapabilities {
+    supportsBugReport: boolean;
+    bugReportZVersion?: string | undefined;
+    supportsBugReportZ: boolean;
+    supportsBugReportZProgress: boolean;
+    supportsBugReportZStream: boolean;
+}
 
-    supportProgress: boolean;
-    supportStream: boolean;
+export interface BugReportZOptions {
+    signal?: AbortSignal;
+    /**
+     * A callback that will be called when progress is updated.
+     *
+     * Specify `onProgress` when `supportsBugReportZProgress` is `false` will throw an error.
+     */
+    onProgress?: ((completed: string, total: string) => void) | undefined;
 }
 
-export class BugReportZ extends AdbCommandBase {
-    public static VERSION_REGEX = /(\d+)\.(\d+)/;
+export class BugReport extends AdbCommandBase {
+    static VERSION_REGEX = /(\d+)\.(\d+)/;
 
-    public static BEGIN_REGEX = /BEGIN:(.*)/;
+    static BEGIN_REGEX = /BEGIN:(.*)/;
 
-    public static PROGRESS_REGEX = /PROGRESS:(.*)\/(.*)/;
+    static PROGRESS_REGEX = /PROGRESS:(.*)\/(.*)/;
 
-    public static OK_REGEX = /OK:(.*)/;
+    static OK_REGEX = /OK:(.*)/;
 
-    public static FAIL_REGEX = /FAIL:(.*)/;
+    static FAIL_REGEX = /FAIL:(.*)/;
 
     /**
-     * Retrieve the version of bugreportz.
-     *
-     * @returns a `BugReportVersion` object, or `undefined` if `bugreportz` is not available.
+     * Queries the device's bugreport capabilities.
      */
-    public async version(): Promise<BugReportZVersion | undefined> {
+    static async queryCapabilities(adb: Adb): Promise<BugReport> {
         // bugreportz requires shell protocol
-        if (!AdbSubprocessShellProtocol.isSupported(this.adb)) {
-            return undefined;
+        if (!AdbSubprocessShellProtocol.isSupported(adb)) {
+            return new BugReport(adb, {
+                supportsBugReport: true,
+                bugReportZVersion: undefined,
+                supportsBugReportZ: false,
+                supportsBugReportZProgress: false,
+                supportsBugReportZStream: false,
+            });
         }
 
-        const { stderr, exitCode } = await this.adb.subprocess.spawnAndWait([
+        const { stderr, exitCode } = await adb.subprocess.spawnAndWait([
             "bugreportz",
             "-v",
         ]);
         if (exitCode !== 0 || stderr === "") {
-            return undefined;
+            return new BugReport(adb, {
+                supportsBugReport: true,
+                bugReportZVersion: undefined,
+                supportsBugReportZ: false,
+                supportsBugReportZProgress: false,
+                supportsBugReportZStream: false,
+            });
         }
 
-        const match = stderr.match(BugReportZ.VERSION_REGEX);
+        const match = stderr.match(BugReport.VERSION_REGEX);
         if (!match) {
-            return undefined;
+            return new BugReport(adb, {
+                supportsBugReport: true,
+                bugReportZVersion: undefined,
+                supportsBugReportZ: false,
+                supportsBugReportZProgress: false,
+                supportsBugReportZStream: false,
+            });
         }
 
-        const major = parseInt(match[1]!, 10);
-        const minor = parseInt(match[2]!, 10);
-        return {
-            major,
-            minor,
+        const [major, minor] = match[0]
+            .split(".")
+            .map((x) => parseInt(x, 10)) as [number, number];
+        return new BugReport(adb, {
+            // Before BugReportZ version 1.2 (Android 12), BugReport was deprecated but still works.
+            supportsBugReport: major === 1 && minor <= 1,
+            bugReportZVersion: match[0],
+            supportsBugReportZ: true,
+            supportsBugReportZProgress: major > 1 || minor >= 1,
+            supportsBugReportZStream: major > 1 || minor >= 2,
+        });
+    }
+
+    #supportsBugReport: boolean;
+    /**
+     * Gets whether the device supports flat (text file, non-zipped) bugreport.
+     *
+     * Should be `true` for Android version <= 11.
+     */
+    get supportsBugReport() {
+        return this.#supportsBugReport;
+    }
 
-            supportProgress: this.supportProgress(major, minor),
-            supportStream: this.supportStream(major, minor),
-        };
+    #bugReportZVersion: string | undefined;
+    /**
+     * Gets the version of BugReportZ.
+     *
+     * Will be `undefined` if BugReportZ is not supported.
+     */
+    get bugReportZVersion() {
+        return this.#bugReportZVersion;
     }
 
-    public supportProgress(major: number, minor: number): boolean {
-        return major > 1 || minor >= 1;
+    #supportsBugReportZ: boolean;
+    /**
+     * Gets whether the device supports zipped bugreport.
+     *
+     * Should be `true` for Android version >= 7.
+     */
+    get supportsBugReportZ() {
+        return this.#supportsBugReportZ;
     }
 
+    #supportsBugReportZProgress: boolean;
     /**
-     * Create a zipped bugreport file.
+     * Gets whether the device supports progress report for zipped bugreport.
      *
-     * Compare to `stream`, this method will write the output to a file on device.
+     * Should be `true` for Android version >= 8.
+     */
+    get supportsBugReportZProgress() {
+        return this.#supportsBugReportZProgress;
+    }
+
+    #supportsBugReportZStream: boolean;
+    /**
+     * Gets whether the device supports streaming zipped bugreport.
+     *
+     * Should be `true` for Android version >= 12.
+     */
+    get supportsBugReportZStream() {
+        return this.#supportsBugReportZStream;
+    }
+
+    constructor(adb: Adb, capabilities: BugReportCapabilities) {
+        super(adb);
+
+        this.#supportsBugReport = capabilities.supportsBugReport;
+        this.#bugReportZVersion = capabilities.bugReportZVersion;
+        this.#supportsBugReportZ = capabilities.supportsBugReportZ;
+        this.#supportsBugReportZProgress =
+            capabilities.supportsBugReportZProgress;
+        this.#supportsBugReportZStream = capabilities.supportsBugReportZStream;
+    }
+
+    /**
+     * Creates a legacy, non-zipped bugreport file, or throws an error if `supportsBugReport` is `false`.
+     *
+     * @returns A flat (text file, non-zipped) bugreport.
+     */
+    bugReport(): ReadableStream<Uint8Array> {
+        if (!this.#supportsBugReport) {
+            throw new Error(
+                "Flat (text file, non-zipped) bugreport is not supported.",
+            );
+        }
+
+        return new WrapReadableStream(async () => {
+            // https://cs.android.com/android/platform/superproject/+/master:frameworks/native/cmds/bugreport/bugreport.cpp;drc=9b73bf07d73dbab5b792632e1e233edbad77f5fd;bpv=0;bpt=0
+            const process = await this.adb.subprocess.spawn(["bugreport"]);
+            return process.stdout;
+        });
+    }
+
+    /**
+     * Creates a zipped bugreport file, or throws an error if `supportsBugReportZ` is `false`.
+     *
+     * Compare to `bugReportZStream`, this method will write the output to a file on device.
      * You can pull it later using sync protocol.
      *
-     * @param onProgress Progress callback. Only specify this if `supportsProgress` is `true`.
-     * @returns The path of the bugreport file.
+     * @returns The path to the generated bugreport file on device filesystem.
      */
-    public async generate(
-        onProgress?: (progress: string, total: string) => void
-    ): Promise<string> {
-        const process = await this.adb.subprocess.spawn([
-            "bugreportz",
-            ...(onProgress ? ["-p"] : []),
-        ]);
+    async bugReportZ(options?: BugReportZOptions): Promise<string> {
+        if (options?.signal?.aborted) {
+            throw options?.signal.reason ?? new Error("Aborted");
+        }
+
+        if (!this.#supportsBugReportZ) {
+            throw new Error("bugreportz is not supported");
+        }
+
+        const args = ["bugreportz"];
+        if (options?.onProgress) {
+            if (!this.#supportsBugReportZProgress) {
+                throw new Error("bugreportz progress is not supported");
+            }
+            args.push("-p");
+        }
+
+        const process = await this.adb.subprocess.spawn(args, {
+            protocols: [AdbSubprocessShellProtocol],
+        });
+
+        options?.signal?.addEventListener("abort", () => {
+            void process.kill();
+        });
 
         let filename: string | undefined;
         let error: string | undefined;
@@ -96,29 +218,29 @@ export class BugReportZ extends AdbCommandBase {
                 new WritableStream<string>({
                     write(line) {
                         // `BEGIN:` and `PROGRESS:` only appear when `-p` is specified.
-                        let match = line.match(BugReportZ.PROGRESS_REGEX);
+                        let match = line.match(BugReport.PROGRESS_REGEX);
                         if (match) {
-                            onProgress?.(match[1]!, match[2]!);
+                            options?.onProgress?.(match[1]!, match[2]!);
                         }
 
-                        match = line.match(BugReportZ.BEGIN_REGEX);
+                        match = line.match(BugReport.BEGIN_REGEX);
                         if (match) {
                             filename = match[1]!;
                         }
 
-                        match = line.match(BugReportZ.OK_REGEX);
+                        match = line.match(BugReport.OK_REGEX);
                         if (match) {
                             filename = match[1];
                         }
 
-                        match = line.match(BugReportZ.FAIL_REGEX);
+                        match = line.match(BugReport.FAIL_REGEX);
                         if (match) {
                             // Don't report error now
                             // We want to gather all output.
                             error = match[1];
                         }
                     },
-                })
+                }),
             );
 
         if (error) {
@@ -133,23 +255,24 @@ export class BugReportZ extends AdbCommandBase {
         return filename;
     }
 
-    public supportStream(major: number, minor: number): boolean {
-        return major > 1 || minor >= 2;
-    }
-
-    public stream(): ReadableStream<Uint8Array> {
+    /**
+     * Creates a zipped bugreport file, or throws an error if `supportsBugReportZStream` is `false`.
+     *
+     * @returns The content of the generated bugreport file.
+     */
+    bugReportZStream(): ReadableStream<Uint8Array> {
         return new PushReadableStream(async (controller) => {
-            const process = await this.adb.subprocess.spawn([
-                "bugreportz",
-                "-s",
-            ]);
+            const process = await this.adb.subprocess.spawn(
+                ["bugreportz", "-s"],
+                { protocols: [AdbSubprocessShellProtocol] },
+            );
             process.stdout
                 .pipeTo(
                     new WritableStream({
                         async write(chunk) {
                             await controller.enqueue(chunk);
                         },
-                    })
+                    }),
                 )
                 .catch((e) => {
                     controller.error(e);
@@ -161,7 +284,7 @@ export class BugReportZ extends AdbCommandBase {
                         write(chunk) {
                             controller.error(new Error(chunk));
                         },
-                    })
+                    }),
                 )
                 .catch((e) => {
                     controller.error(e);
@@ -169,14 +292,57 @@ export class BugReportZ extends AdbCommandBase {
             await process.exit;
         });
     }
-}
 
-// https://cs.android.com/android/platform/superproject/+/master:frameworks/native/cmds/bugreport/bugreport.cpp;drc=9b73bf07d73dbab5b792632e1e233edbad77f5fd;bpv=0;bpt=0
-export class BugReport extends AdbCommandBase {
-    public generate(): ReadableStream<Uint8Array> {
-        return new WrapReadableStream(async () => {
-            const process = await this.adb.subprocess.spawn(["bugreport"]);
-            return process.stdout;
-        });
+    /**
+     * Automatically choose the best bugreport method.
+     *
+     * * If `supportsBugReportZStream` is `true`, this method will return a stream of zipped bugreport.
+     * * If `supportsBugReportZ` is `true`, this method will return a stream of zipped bugreport, and will delete the file on device after the stream is closed.
+     * * If `supportsBugReport` is `true`, this method will return a stream of flat bugreport.
+     *
+     * @param onProgress
+     * If `supportsBugReportZStream` is `false` and `supportsBugReportZProgress` is `true`,
+     * this callback will be called when progress is updated.
+     */
+    automatic(onProgress?: (completed: string, total: string) => void): {
+        type: "bugreport" | "bugreportz";
+        stream: ReadableStream<Uint8Array>;
+    } {
+        if (this.#supportsBugReportZStream) {
+            return { type: "bugreportz", stream: this.bugReportZStream() };
+        }
+
+        if (this.#supportsBugReportZ) {
+            let path: string | undefined;
+            let sync: AdbSync | undefined;
+            const controller = new AbortController();
+            const cleanup = async () => {
+                controller.abort();
+                await sync?.dispose();
+                if (path) {
+                    await this.adb.rm(path);
+                }
+            };
+
+            return {
+                type: "bugreportz",
+                stream: new WrapReadableStream({
+                    start: async () => {
+                        path = await this.bugReportZ({
+                            signal: controller.signal,
+                            onProgress: this.#supportsBugReportZProgress
+                                ? onProgress
+                                : undefined,
+                        });
+                        sync = await this.adb.sync();
+                        return sync.read(path);
+                    },
+                    cancel: cleanup,
+                    close: cleanup,
+                }),
+            };
+        }
+
+        return { type: "bugreport", stream: this.bugReport() };
     }
 }

package/src/cmd.ts

@@ -1,67 +1,101 @@
-import type { Adb, AdbSubprocessProtocolConstructor } from "@yume-chan/adb";
+import type {
+    Adb,
+    AdbSubprocessProtocol,
+    AdbSubprocessProtocolConstructor,
+    AdbSubprocessWaitResult,
+} from "@yume-chan/adb";
 import {
     AdbCommandBase,
     AdbFeature,
     AdbSubprocessNoneProtocol,
     AdbSubprocessShellProtocol,
 } from "@yume-chan/adb";
+import { ConcatStringStream, DecodeUtf8Stream } from "@yume-chan/stream-extra";
 
 export class Cmd extends AdbCommandBase {
-    private _supportsShellV2: boolean;
-    private _supportsCmd: boolean;
-    private _supportsAbb: boolean;
-    private _supportsAbbExec: boolean;
-
-    public get supportsShellV2() {
-        return this._supportsShellV2;
+    #supportsShellV2: boolean;
+    get supportsShellV2() {
+        return this.#supportsShellV2;
     }
-    public get supportsCmd() {
-        return this._supportsCmd;
+
+    #supportsCmd: boolean;
+    get supportsCmd() {
+        return this.#supportsCmd;
     }
-    public get supportsAbb() {
-        return this._supportsAbb;
+
+    #supportsAbb: boolean;
+    get supportsAbb() {
+        return this.#supportsAbb;
     }
-    public get supportsAbbExec() {
-        return this._supportsAbbExec;
+
+    #supportsAbbExec: boolean;
+    get supportsAbbExec() {
+        return this.#supportsAbbExec;
     }
 
-    public constructor(adb: Adb) {
+    constructor(adb: Adb) {
         super(adb);
-        this._supportsShellV2 = adb.supportsFeature(AdbFeature.ShellV2);
-        this._supportsCmd = adb.supportsFeature(AdbFeature.Cmd);
-        this._supportsAbb = adb.supportsFeature(AdbFeature.Abb);
-        this._supportsAbbExec = adb.supportsFeature(AdbFeature.AbbExec);
+        this.#supportsShellV2 = adb.supportsFeature(AdbFeature.ShellV2);
+        this.#supportsCmd = adb.supportsFeature(AdbFeature.Cmd);
+        this.#supportsAbb = adb.supportsFeature(AdbFeature.Abb);
+        this.#supportsAbbExec = adb.supportsFeature(AdbFeature.AbbExec);
     }
 
-    public async spawn(
+    async spawn(
         shellProtocol: boolean,
         command: string,
         ...args: string[]
-    ) {
+    ): Promise<AdbSubprocessProtocol> {
         let supportsAbb: boolean;
-        let supportsCmd: boolean = this.supportsCmd;
+        let supportsCmd: boolean = this.#supportsCmd;
         let service: string;
         let Protocol: AdbSubprocessProtocolConstructor;
         if (shellProtocol) {
-            supportsAbb = this._supportsAbb;
+            supportsAbb = this.#supportsAbb;
             supportsCmd &&= this.supportsShellV2;
             service = "abb";
             Protocol = AdbSubprocessShellProtocol;
         } else {
-            supportsAbb = this._supportsAbbExec;
+            supportsAbb = this.#supportsAbbExec;
             service = "abb_exec";
             Protocol = AdbSubprocessNoneProtocol;
         }
 
         if (supportsAbb) {
-            const socket = await this.adb.createSocket(
-                `${service}:${command}\0${args.join("\0")}\0`
+            return new Protocol(
+                await this.adb.createSocket(
+                    `${service}:${command}\0${args.join("\0")}\0`,
+                ),
             );
-            return new Protocol(socket);
-        } else if (supportsCmd) {
+        }
+
+        if (supportsCmd) {
             return Protocol.raw(this.adb, `cmd ${command} ${args.join(" ")}`);
-        } else {
-            throw new Error("Not supported");
         }
+
+        throw new Error("Not supported");
+    }
+
+    async spawnAndWait(
+        command: string,
+        ...args: string[]
+    ): Promise<AdbSubprocessWaitResult> {
+        const process = await this.spawn(true, command, ...args);
+
+        const [stdout, stderr, exitCode] = await Promise.all([
+            process.stdout
+                .pipeThrough(new DecodeUtf8Stream())
+                .pipeThrough(new ConcatStringStream()),
+            process.stderr
+                .pipeThrough(new DecodeUtf8Stream())
+                .pipeThrough(new ConcatStringStream()),
+            process.exit,
+        ]);
+
+        return {
+            stdout,
+            stderr,
+            exitCode,
+        };
     }
 }