@yume-chan/android-bin 0.0.0-20240714132542

package/src/bug-report.ts

@@ -0,0 +1,348 @@
+// cspell: ignore bugreport
+// cspell: ignore bugreportz
+
+import type { Adb, AdbSync } from "@yume-chan/adb";
+import { AdbCommandBase, AdbSubprocessShellProtocol } from "@yume-chan/adb";
+import type { AbortSignal, ReadableStream } from "@yume-chan/stream-extra";
+import {
+    AbortController,
+    PushReadableStream,
+    SplitStringStream,
+    TextDecoderStream,
+    WrapReadableStream,
+    WritableStream,
+} from "@yume-chan/stream-extra";
+
+export interface BugReportCapabilities {
+    supportsBugReport: boolean;
+    bugReportZVersion?: string | undefined;
+    supportsBugReportZ: boolean;
+    supportsBugReportZProgress: boolean;
+    supportsBugReportZStream: 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 BugReport extends AdbCommandBase {
+    static VERSION_REGEX: RegExp = /(\d+)\.(\d+)/;
+
+    static BEGIN_REGEX: RegExp = /BEGIN:(.*)/;
+
+    static PROGRESS_REGEX: RegExp = /PROGRESS:(.*)\/(.*)/;
+
+    static OK_REGEX: RegExp = /OK:(.*)/;
+
+    static FAIL_REGEX: RegExp = /FAIL:(.*)/;
+
+    /**
+     * Queries the device's bugreport capabilities.
+     */
+    static async queryCapabilities(adb: Adb): Promise<BugReport> {
+        // bugreportz requires shell protocol
+        if (!AdbSubprocessShellProtocol.isSupported(adb)) {
+            return new BugReport(adb, {
+                supportsBugReport: true,
+                bugReportZVersion: undefined,
+                supportsBugReportZ: false,
+                supportsBugReportZProgress: false,
+                supportsBugReportZStream: false,
+            });
+        }
+
+        const { stderr, exitCode } = await adb.subprocess.spawnAndWait([
+            "bugreportz",
+            "-v",
+        ]);
+        if (exitCode !== 0 || stderr === "") {
+            return new BugReport(adb, {
+                supportsBugReport: true,
+                bugReportZVersion: undefined,
+                supportsBugReportZ: false,
+                supportsBugReportZProgress: false,
+                supportsBugReportZStream: false,
+            });
+        }
+
+        const match = stderr.match(BugReport.VERSION_REGEX);
+        if (!match) {
+            return new BugReport(adb, {
+                supportsBugReport: true,
+                bugReportZVersion: undefined,
+                supportsBugReportZ: false,
+                supportsBugReportZProgress: false,
+                supportsBugReportZStream: false,
+            });
+        }
+
+        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(): boolean {
+        return this.#supportsBugReport;
+    }
+
+    #bugReportZVersion: string | undefined;
+    /**
+     * Gets the version of BugReportZ.
+     *
+     * Will be `undefined` if BugReportZ is not supported.
+     */
+    get bugReportZVersion(): string | undefined {
+        return this.#bugReportZVersion;
+    }
+
+    #supportsBugReportZ: boolean;
+    /**
+     * Gets whether the device supports zipped bugreport.
+     *
+     * Should be `true` for Android version >= 7.
+     */
+    get supportsBugReportZ(): boolean {
+        return this.#supportsBugReportZ;
+    }
+
+    #supportsBugReportZProgress: boolean;
+    /**
+     * Gets whether the device supports progress report for zipped bugreport.
+     *
+     * Should be `true` for Android version >= 8.
+     */
+    get supportsBugReportZProgress(): boolean {
+        return this.#supportsBugReportZProgress;
+    }
+
+    #supportsBugReportZStream: boolean;
+    /**
+     * Gets whether the device supports streaming zipped bugreport.
+     *
+     * Should be `true` for Android version >= 12.
+     */
+    get supportsBugReportZStream(): boolean {
+        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.
+     *
+     * @returns The path to the generated bugreport file on device filesystem.
+     */
+    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;
+
+        await process.stdout
+            .pipeThrough(new TextDecoderStream())
+            .pipeThrough(new SplitStringStream("\n"))
+            .pipeTo(
+                new WritableStream<string>({
+                    write(line) {
+                        // `BEGIN:` and `PROGRESS:` only appear when `-p` is specified.
+                        let match = line.match(BugReport.PROGRESS_REGEX);
+                        if (match) {
+                            options?.onProgress?.(match[1]!, match[2]!);
+                        }
+
+                        match = line.match(BugReport.BEGIN_REGEX);
+                        if (match) {
+                            filename = match[1]!;
+                        }
+
+                        match = line.match(BugReport.OK_REGEX);
+                        if (match) {
+                            filename = match[1];
+                        }
+
+                        match = line.match(BugReport.FAIL_REGEX);
+                        if (match) {
+                            // Don't report error now
+                            // We want to gather all output.
+                            error = match[1];
+                        }
+                    },
+                }),
+            );
+
+        if (error) {
+            throw new Error(error);
+        }
+
+        if (!filename) {
+            throw new Error("bugreportz did not return file name");
+        }
+
+        // Design choice: we don't automatically pull the file to avoid more dependency on `@yume-chan/adb`
+        return filename;
+    }
+
+    /**
+     * 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"],
+                { protocols: [AdbSubprocessShellProtocol] },
+            );
+            process.stdout
+                .pipeTo(
+                    new WritableStream({
+                        async write(chunk) {
+                            await controller.enqueue(chunk);
+                        },
+                    }),
+                )
+                .catch((e) => {
+                    controller.error(e);
+                });
+            process.stderr
+                .pipeThrough(new TextDecoderStream())
+                .pipeTo(
+                    new WritableStream({
+                        write(chunk) {
+                            controller.error(new Error(chunk));
+                        },
+                    }),
+                )
+                .catch((e) => {
+                    controller.error(e);
+                });
+            await process.exit;
+        });
+    }
+
+    /**
+     * 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

@@ -0,0 +1,113 @@
+import type {
+    Adb,
+    AdbSubprocessProtocol,
+    AdbSubprocessProtocolConstructor,
+    AdbSubprocessWaitResult,
+} from "@yume-chan/adb";
+import {
+    AdbCommandBase,
+    AdbFeature,
+    AdbSubprocessNoneProtocol,
+    AdbSubprocessShellProtocol,
+} from "@yume-chan/adb";
+import { ConcatStringStream, TextDecoderStream } from "@yume-chan/stream-extra";
+
+export class Cmd extends AdbCommandBase {
+    #supportsShellV2: boolean;
+    get supportsShellV2(): boolean {
+        return this.#supportsShellV2;
+    }
+
+    #supportsCmd: boolean;
+    get supportsCmd(): boolean {
+        return this.#supportsCmd;
+    }
+
+    #supportsAbb: boolean;
+    get supportsAbb(): boolean {
+        return this.#supportsAbb;
+    }
+
+    #supportsAbbExec: boolean;
+    get supportsAbbExec(): boolean {
+        return this.#supportsAbbExec;
+    }
+
+    constructor(adb: Adb) {
+        super(adb);
+        this.#supportsShellV2 = adb.canUseFeature(AdbFeature.ShellV2);
+        this.#supportsCmd = adb.canUseFeature(AdbFeature.Cmd);
+        this.#supportsAbb = adb.canUseFeature(AdbFeature.Abb);
+        this.#supportsAbbExec = adb.canUseFeature(AdbFeature.AbbExec);
+    }
+
+    /**
+     * Spawn a new `cmd` command. It will use ADB's `abb` command if available.
+     *
+     * @param shellProtocol
+     * Whether to use shell protocol. If `true`, `stdout` and `stderr` will be separated.
+     *
+     * `cmd` doesn't use PTY, so even when shell protocol is used,
+     * resizing terminal size and closing `stdin` are not supported.
+     * @param command The command to run.
+     * @param args The arguments to pass to the command.
+     * @returns An `AdbSubprocessProtocol` that provides output streams.
+     */
+    async spawn(
+        shellProtocol: boolean,
+        command: string,
+        ...args: string[]
+    ): Promise<AdbSubprocessProtocol> {
+        let supportsAbb: boolean;
+        let supportsCmd: boolean = this.#supportsCmd;
+        let service: string;
+        let Protocol: AdbSubprocessProtocolConstructor;
+        if (shellProtocol) {
+            supportsAbb = this.#supportsAbb;
+            supportsCmd &&= this.supportsShellV2;
+            service = "abb";
+            Protocol = AdbSubprocessShellProtocol;
+        } else {
+            supportsAbb = this.#supportsAbbExec;
+            service = "abb_exec";
+            Protocol = AdbSubprocessNoneProtocol;
+        }
+
+        if (supportsAbb) {
+            return new Protocol(
+                await this.adb.createSocket(
+                    `${service}:${command}\0${args.join("\0")}\0`,
+                ),
+            );
+        }
+
+        if (supportsCmd) {
+            return Protocol.raw(this.adb, `cmd ${command} ${args.join(" ")}`);
+        }
+
+        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 TextDecoderStream())
+                .pipeThrough(new ConcatStringStream()),
+            process.stderr
+                .pipeThrough(new TextDecoderStream())
+                .pipeThrough(new ConcatStringStream()),
+            process.exit,
+        ]);
+
+        return {
+            stdout,
+            stderr,
+            exitCode,
+        };
+    }
+}

package/src/demo-mode.ts

@@ -0,0 +1,232 @@
+// cspell: ignore carriernetworkchange
+// cspell: ignore powersave
+// cspell: ignore nosim
+// cspell: ignore systemui
+// cspell: ignore sysui
+
+import type { Adb } from "@yume-chan/adb";
+import { AdbCommandBase } from "@yume-chan/adb";
+
+import { Settings } from "./settings.js";
+
+export enum DemoModeSignalStrength {
+    Hidden = "null",
+    Level0 = "0",
+    Level1 = "1",
+    Level2 = "2",
+    Level3 = "3",
+    Level4 = "4",
+}
+
+// https://cs.android.com/android/platform/superproject/+/master:frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/connectivity/NetworkControllerImpl.java;l=1362;drc=3b775bf7ad89902f94e03d191b0d8fbdebf2bdbf
+export const DemoModeMobileDataTypes = [
+    "1x",
+    "3g",
+    "4g",
+    "4g+",
+    "5g",
+    "5ge",
+    "5g+",
+    "e",
+    "g",
+    "h",
+    "h+",
+    "lte",
+    "lte+",
+    "dis",
+    "not",
+    "null",
+] as const;
+
+export type DemoModeMobileDataType = (typeof DemoModeMobileDataTypes)[number];
+
+// https://cs.android.com/android/platform/superproject/+/master:frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/StatusBar.java;l=3136
+export const DemoModeStatusBarModes = [
+    "opaque",
+    "translucent",
+    "semi-transparent",
+    "transparent",
+    "warning",
+] as const;
+
+export type DemoModeStatusBarMode = (typeof DemoModeStatusBarModes)[number];
+
+export class DemoMode extends AdbCommandBase {
+    #settings: Settings;
+
+    constructor(adb: Adb) {
+        super(adb);
+        this.#settings = new Settings(adb);
+    }
+
+    static readonly ALLOWED_SETTING_KEY = "sysui_demo_allowed";
+
+    // Demo Mode actually doesn't have a setting indicates its enablement
+    // However Developer Mode menu uses this key
+    // So we can only try our best to guess if it's enabled
+    static readonly ENABLED_SETTING_KEY = "sysui_tuner_demo_on";
+
+    async getAllowed(): Promise<boolean> {
+        const output = await this.#settings.get(
+            "global",
+            DemoMode.ALLOWED_SETTING_KEY,
+        );
+        return output === "1";
+    }
+
+    async setAllowed(value: boolean): Promise<void> {
+        if (value) {
+            await this.#settings.put(
+                "global",
+                DemoMode.ALLOWED_SETTING_KEY,
+                "1",
+            );
+        } else {
+            await this.setEnabled(false);
+            await this.#settings.delete("global", DemoMode.ALLOWED_SETTING_KEY);
+        }
+    }
+
+    async getEnabled(): Promise<boolean> {
+        const result = await this.#settings.get(
+            "global",
+            DemoMode.ENABLED_SETTING_KEY,
+        );
+        return result === "1";
+    }
+
+    async setEnabled(value: boolean): Promise<void> {
+        if (value) {
+            await this.#settings.put(
+                "global",
+                DemoMode.ENABLED_SETTING_KEY,
+                "1",
+            );
+        } else {
+            await this.#settings.delete("global", DemoMode.ENABLED_SETTING_KEY);
+            await this.broadcast("exit");
+        }
+    }
+
+    async broadcast(
+        command: string,
+        extra?: Record<string, string>,
+    ): Promise<void> {
+        await this.adb.subprocess.spawnAndWaitLegacy([
+            "am",
+            "broadcast",
+            "-a",
+            "com.android.systemui.demo",
+            "-e",
+            "command",
+            command,
+            ...(extra
+                ? Object.entries(extra).flatMap(([key, value]) => [
+                      "-e",
+                      key,
+                      value,
+                  ])
+                : []),
+        ]);
+    }
+
+    async setBatteryLevel(level: number): Promise<void> {
+        await this.broadcast("battery", { level: level.toString() });
+    }
+
+    async setBatteryCharging(value: boolean): Promise<void> {
+        await this.broadcast("battery", { plugged: value.toString() });
+    }
+
+    async setPowerSaveMode(value: boolean): Promise<void> {
+        await this.broadcast("battery", { powersave: value.toString() });
+    }
+
+    async setAirplaneMode(show: boolean): Promise<void> {
+        await this.broadcast("network", { airplane: show ? "show" : "hide" });
+    }
+
+    async setWifiSignalStrength(value: DemoModeSignalStrength): Promise<void> {
+        await this.broadcast("network", { wifi: "show", level: value });
+    }
+
+    async setMobileDataType(value: DemoModeMobileDataType): Promise<void> {
+        for (let i = 0; i < 2; i += 1) {
+            await this.broadcast("network", {
+                mobile: "show",
+                sims: "1",
+                nosim: "hide",
+                slot: "0",
+                datatype: value,
+                fully: "true",
+                roam: "false",
+                level: "4",
+                inflate: "false",
+                activity: "in",
+                carriernetworkchange: "hide",
+            });
+        }
+    }
+
+    async setMobileSignalStrength(
+        value: DemoModeSignalStrength,
+    ): Promise<void> {
+        await this.broadcast("network", { mobile: "show", level: value });
+    }
+
+    async setNoSimCardIcon(show: boolean): Promise<void> {
+        await this.broadcast("network", { nosim: show ? "show" : "hide" });
+    }
+
+    async setStatusBarMode(mode: DemoModeStatusBarMode): Promise<void> {
+        await this.broadcast("bars", { mode });
+    }
+
+    async setVibrateModeEnabled(value: boolean): Promise<void> {
+        // https://cs.android.com/android/platform/superproject/+/master:frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DemoStatusIcons.java;l=103
+        await this.broadcast("status", { volume: value ? "vibrate" : "hide" });
+    }
+
+    async setBluetoothConnected(value: boolean): Promise<void> {
+        // https://cs.android.com/android/platform/superproject/+/master:frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DemoStatusIcons.java;l=114
+        await this.broadcast("status", {
+            bluetooth: value ? "connected" : "hide",
+        });
+    }
+
+    async setLocatingIcon(show: boolean): Promise<void> {
+        await this.broadcast("status", { location: show ? "show" : "hide" });
+    }
+
+    async setAlarmIcon(show: boolean): Promise<void> {
+        await this.broadcast("status", { alarm: show ? "show" : "hide" });
+    }
+
+    async setSyncingIcon(show: boolean): Promise<void> {
+        await this.broadcast("status", { sync: show ? "show" : "hide" });
+    }
+
+    async setMuteIcon(show: boolean): Promise<void> {
+        await this.broadcast("status", { mute: show ? "show" : "hide" });
+    }
+
+    async setSpeakerPhoneIcon(show: boolean): Promise<void> {
+        await this.broadcast("status", {
+            speakerphone: show ? "show" : "hide",
+        });
+    }
+
+    async setNotificationsVisibility(show: boolean): Promise<void> {
+        // https://cs.android.com/android/platform/superproject/+/master:frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/StatusBar.java;l=3131
+        await this.broadcast("notifications", { visible: show.toString() });
+    }
+
+    async setTime(hour: number, minute: number): Promise<void> {
+        await this.broadcast("clock", {
+            // cspell: disable-next-line
+            hhmm:
+                hour.toString().padStart(2, "0") +
+                minute.toString().padStart(2, "0"),
+        });
+    }
+}