@yume-chan/android-bin 0.0.23 → 1.0.0

package/src/logcat.ts

@@ -5,42 +5,50 @@ 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";
-import type { AsyncExactReadable } from "@yume-chan/struct";
-import Struct, { decodeUtf8 } from "@yume-chan/struct";
+import type { AsyncExactReadable, StructValue } from "@yume-chan/struct";
+import { decodeUtf8, struct, u16, u32 } from "@yume-chan/struct";
 
 // `adb logcat` is an alias to `adb shell logcat`
 // so instead of adding to core library, it's implemented here
 
 // https://cs.android.com/android/platform/superproject/+/master:system/logging/liblog/include/android/log.h;l=141;drc=82b5738732161dbaafb2e2f25cce19cd26b9157d
-export enum LogId {
-    All = -1,
-    Main,
-    Radio,
-    Events,
-    System,
-    Crash,
-    Stats,
-    Security,
-    Kernel,
-}
+export const LogId = {
+    All: -1,
+    Main: 0,
+    Radio: 1,
+    Events: 2,
+    System: 3,
+    Crash: 4,
+    Stats: 5,
+    Security: 6,
+    Kernel: 7,
+} as const;
+
+export type LogId = (typeof LogId)[keyof typeof LogId];
+
+const LogIdName =
+    /* #__PURE__ */
+    (() => Object.fromEntries(Object.entries(LogId).map(([k, v]) => [v, k])))();
 
 // https://cs.android.com/android/platform/superproject/+/master:system/logging/liblog/include/android/log.h;l=73;drc=82b5738732161dbaafb2e2f25cce19cd26b9157d
-export enum AndroidLogPriority {
-    Unknown,
-    Default,
-    Verbose,
-    Debug,
-    Info,
-    Warn,
-    Error,
-    Fatal,
-    Silent,
-}
+export const AndroidLogPriority = {
+    Unknown: 0,
+    Default: 1,
+    Verbose: 2,
+    Debug: 3,
+    Info: 4,
+    Warn: 5,
+    Error: 6,
+    Fatal: 7,
+    Silent: 8,
+} as const;
+
+export type AndroidLogPriority =
+    (typeof AndroidLogPriority)[keyof typeof AndroidLogPriority];
 
 // https://cs.android.com/android/platform/superproject/+/master:system/logging/liblog/logprint.cpp;l=140;drc=8dbf3b2bb6b6d1652d9797e477b9abd03278bb79
 export const AndroidLogPriorityToCharacter: Record<AndroidLogPriority, string> =
@@ -56,16 +64,18 @@ export const AndroidLogPriorityToCharacter: Record<AndroidLogPriority, string> =
         [AndroidLogPriority.Silent]: "S",
     };
 
-export enum LogcatFormat {
-    Brief,
-    Process,
-    Tag,
-    Thread,
-    Raw,
-    Time,
-    ThreadTime,
-    Long,
-}
+export const LogcatFormat = {
+    Brief: 0,
+    Process: 1,
+    Tag: 2,
+    Thread: 3,
+    Raw: 4,
+    Time: 5,
+    ThreadTime: 6,
+    Long: 7,
+} as const;
+
+export type LogcatFormat = (typeof LogcatFormat)[keyof typeof LogcatFormat];
 
 export interface LogcatFormatModifiers {
     microseconds?: boolean;
@@ -85,28 +95,34 @@ export interface LogcatOptions {
     ids?: LogId[];
 }
 
-const NANOSECONDS_PER_SECOND = BigInt(1e9);
+const NANOSECONDS_PER_SECOND = /* #__PURE__ */ BigInt(1e9);
 
 // https://cs.android.com/android/platform/superproject/+/master:system/logging/liblog/include/log/log_read.h;l=39;drc=82b5738732161dbaafb2e2f25cce19cd26b9157d
-export const LoggerEntry = new Struct({ littleEndian: true })
-    .uint16("payloadSize")
-    .uint16("headerSize")
-    .int32("pid")
-    .uint32("tid")
-    .uint32("seconds")
-    .uint32("nanoseconds")
-    .uint32("logId")
-    .uint32("uid")
-    .extra({
-        get timestamp() {
-            return (
-                BigInt(this.seconds) * NANOSECONDS_PER_SECOND +
-                BigInt(this.nanoseconds)
-            );
+export const LoggerEntry = struct(
+    {
+        payloadSize: u16,
+        headerSize: u16,
+        pid: u32,
+        tid: u32,
+        seconds: u32,
+        nanoseconds: u32,
+        logId: u32,
+        uid: u32,
+    },
+    {
+        littleEndian: true,
+        extra: {
+            get timestamp(): bigint {
+                return (
+                    BigInt(this.seconds) * NANOSECONDS_PER_SECOND +
+                    BigInt(this.nanoseconds)
+                );
+            },
         },
-    });
+    },
+);
 
-export type LoggerEntry = (typeof LoggerEntry)["TDeserializeResult"];
+export type LoggerEntry = StructValue<typeof LoggerEntry>;
 
 // https://cs.android.com/android/platform/superproject/+/master:system/logging/liblog/logprint.cpp;drc=bbe77d66e7bee8bd1f0bc7e5492b5376b0207ef6;bpv=0
 export interface AndroidLogEntry extends LoggerEntry {
@@ -353,6 +369,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 +401,7 @@ export interface LogSize {
 
 export class Logcat extends AdbCommandBase {
     static logIdToName(id: LogId): string {
-        return LogId[id];
+        return LogIdName[id]!;
     }
 
     static logNameToId(name: string): LogId {
@@ -403,12 +420,12 @@ export class Logcat extends AdbCommandBase {
 
     // TODO: logcat: Support output format before Android 10
     // ref https://android-review.googlesource.com/c/platform/system/core/+/748128
-    static readonly LOG_SIZE_REGEX_10 =
+    static readonly LOG_SIZE_REGEX_10: RegExp =
         /(.*): ring buffer is (.*) (.*)B \((.*) (.*)B consumed\), max entry is (.*) B, max payload is (.*) B/;
 
     // Android 11 added `readable` part
     // ref https://android-review.googlesource.com/c/platform/system/core/+/1390940
-    static readonly LOG_SIZE_REGEX_11 =
+    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[]> {
@@ -419,58 +436,53 @@ export class Logcat extends AdbCommandBase {
         ]);
 
         const result: LogSize[] = [];
-        await stdout
-            .pipeThrough(new DecodeUtf8Stream())
-            .pipeThrough(new SplitStringStream("\n"))
-            .pipeTo(
-                new WritableStream({
-                    write(chunk) {
-                        let match = chunk.match(Logcat.LOG_SIZE_REGEX_11);
-                        if (match) {
-                            result.push({
-                                id: Logcat.logNameToId(match[1]!),
-                                size: Logcat.parseSize(
-                                    Number.parseInt(match[2]!, 10),
-                                    match[3]!,
-                                ),
-                                readable: Logcat.parseSize(
-                                    Number.parseInt(match[6]!, 10),
-                                    match[7]!,
-                                ),
-                                consumed: Logcat.parseSize(
-                                    Number.parseInt(match[4]!, 10),
-                                    match[5]!,
-                                ),
-                                maxEntrySize: parseInt(match[8]!, 10),
-                                maxPayloadSize: parseInt(match[9]!, 10),
-                            });
-                            return;
-                        }
-
-                        match = chunk.match(Logcat.LOG_SIZE_REGEX_10);
-                        if (match) {
-                            result.push({
-                                id: Logcat.logNameToId(match[1]!),
-                                size: Logcat.parseSize(
-                                    Number.parseInt(match[2]!, 10),
-                                    match[3]!,
-                                ),
-                                consumed: Logcat.parseSize(
-                                    Number.parseInt(match[4]!, 10),
-                                    match[5]!,
-                                ),
-                                maxEntrySize: parseInt(match[6]!, 10),
-                                maxPayloadSize: parseInt(match[7]!, 10),
-                            });
-                        }
-                    },
-                }),
-            );
+        for await (const line of stdout
+            .pipeThrough(new TextDecoderStream())
+            .pipeThrough(new SplitStringStream("\n"))) {
+            let match = line.match(Logcat.LOG_SIZE_REGEX_11);
+            if (match) {
+                result.push({
+                    id: Logcat.logNameToId(match[1]!),
+                    size: Logcat.parseSize(
+                        Number.parseInt(match[2]!, 10),
+                        match[3]!,
+                    ),
+                    readable: Logcat.parseSize(
+                        Number.parseInt(match[6]!, 10),
+                        match[7]!,
+                    ),
+                    consumed: Logcat.parseSize(
+                        Number.parseInt(match[4]!, 10),
+                        match[5]!,
+                    ),
+                    maxEntrySize: parseInt(match[8]!, 10),
+                    maxPayloadSize: parseInt(match[9]!, 10),
+                });
+                break;
+            }
+
+            match = line.match(Logcat.LOG_SIZE_REGEX_10);
+            if (match) {
+                result.push({
+                    id: Logcat.logNameToId(match[1]!),
+                    size: Logcat.parseSize(
+                        Number.parseInt(match[2]!, 10),
+                        match[3]!,
+                    ),
+                    consumed: Logcat.parseSize(
+                        Number.parseInt(match[4]!, 10),
+                        match[5]!,
+                    ),
+                    maxEntrySize: parseInt(match[6]!, 10),
+                    maxPayloadSize: parseInt(match[7]!, 10),
+                });
+            }
+        }
 
         return result;
     }
 
-    async clear(ids?: LogId[]) {
+    async clear(ids?: LogId[]): Promise<void> {
         const args = ["logcat", "-c"];
         if (ids && ids.length > 0) {
             args.push("-b", Logcat.joinLogId(ids));

package/src/overlay-display.ts

@@ -36,7 +36,7 @@ export class OverlayDisplay extends AdbCommandBase {
                         p.literal("/"),
                         { name: "density", format: p.digits() },
                     ),
-                    1,
+                    { min: 1 },
                 ),
             },
             {
@@ -81,7 +81,7 @@ export class OverlayDisplay extends AdbCommandBase {
         }));
     }
 
-    async set(devices: OverlayDisplayDevice[]) {
+    async set(devices: OverlayDisplayDevice[]): Promise<void> {
         await this.#settings.put(
             "global",
             OverlayDisplay.SETTING_KEY,

package/src/pm.ts

@@ -5,11 +5,11 @@
 
 import type { Adb } from "@yume-chan/adb";
 import { AdbCommandBase, escapeArg } from "@yume-chan/adb";
-import type { Consumable, ReadableStream } from "@yume-chan/stream-extra";
+import type { MaybeConsumable, ReadableStream } from "@yume-chan/stream-extra";
 import {
     ConcatStringStream,
-    DecodeUtf8Stream,
     SplitStringStream,
+    TextDecoderStream,
 } from "@yume-chan/stream-extra";
 
 import { Cmd } from "./cmd.js";
@@ -255,6 +255,32 @@ const PACKAGE_MANAGER_RESOLVE_ACTIVITY_OPTIONS_MAP: Partial<
     user: "--user",
 };
 
+function buildInstallArguments(
+    command: string,
+    options: Partial<PackageManagerInstallOptions> | undefined,
+): string[] {
+    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;
+}
+
 export class PackageManager extends AdbCommandBase {
     #cmd: Cmd;
 
@@ -263,22 +289,6 @@ export class PackageManager extends AdbCommandBase {
         this.#cmd = new Cmd(adb);
     }
 
-    #buildInstallArguments(
-        command: string,
-        options: Partial<PackageManagerInstallOptions> | undefined,
-    ): string[] {
-        const args = buildArguments(
-            ["pm", command],
-            options,
-            PACKAGE_MANAGER_INSTALL_OPTIONS_MAP,
-        );
-        if (!options?.skipExisting) {
-            // Compatibility with old versions of pm
-            args.push("-r");
-        }
-        return args;
-    }
-
     /**
      * Install the apk file.
      *
@@ -288,14 +298,14 @@ export class PackageManager extends AdbCommandBase {
         apks: string[],
         options?: Partial<PackageManagerInstallOptions>,
     ): Promise<string> {
-        const args = this.#buildInstallArguments("install", options);
+        const args = 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();
@@ -312,11 +322,16 @@ 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("install", 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 = buildInstallArguments("install", options);
         args.push(filePath);
 
         try {
@@ -334,25 +349,28 @@ export class PackageManager extends AdbCommandBase {
 
     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("install", options);
-        // Remove `pm` from args, final command will starts with `cmd package install`
+        const args = 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());
 
@@ -377,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);
@@ -399,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);
@@ -440,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) {
@@ -468,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") {
@@ -489,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());
 
@@ -510,12 +533,14 @@ export class PackageManager extends AdbCommandBase {
      * @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);
+    async sessionCreate(
+        options?: Partial<PackageManagerInstallOptions>,
+    ): Promise<number> {
+        const args = buildInstallArguments("install-create", options);
 
         const process = await this.#cmdOrSubprocess(args);
         const output = await process.stdout
-            .pipeThrough(new DecodeUtf8Stream())
+            .pipeThrough(new TextDecoderStream())
             .pipeThrough(new ConcatStringStream())
             .then((output) => output.trim());
 
@@ -527,7 +552,11 @@ export class PackageManager extends AdbCommandBase {
         return Number.parseInt(sessionIdString[1]!, 10);
     }
 
-    async sessionAddSplit(sessionId: number, splitName: string, path: string) {
+    async sessionAddSplit(
+        sessionId: number,
+        splitName: string,
+        path: string,
+    ): Promise<void> {
         const args: string[] = [
             "pm",
             "install-write",
@@ -548,8 +577,8 @@ export class PackageManager extends AdbCommandBase {
         sessionId: number,
         splitName: string,
         size: number,
-        stream: ReadableStream<Consumable<Uint8Array>>,
-    ) {
+        stream: ReadableStream<MaybeConsumable<Uint8Array>>,
+    ): Promise<void> {
         const args: string[] = [
             "pm",
             "install-write",
@@ -562,7 +591,7 @@ export class PackageManager extends AdbCommandBase {
 
         const process = await this.#cmdOrSubprocess(args);
         const output = process.stdout
-            .pipeThrough(new DecodeUtf8Stream())
+            .pipeThrough(new TextDecoderStream())
             .pipeThrough(new ConcatStringStream())
             .then((output) => output.trim());
 
@@ -576,7 +605,7 @@ export class PackageManager extends AdbCommandBase {
         ]);
     }
 
-    async sessionCommit(sessionId: number) {
+    async sessionCommit(sessionId: number): Promise<void> {
         const args: string[] = ["pm", "install-commit", sessionId.toString()];
         const output = await this.adb.subprocess
             .spawnAndWaitLegacy(args)
@@ -586,7 +615,7 @@ export class PackageManager extends AdbCommandBase {
         }
     }
 
-    async sessionAbandon(sessionId: number) {
+    async sessionAbandon(sessionId: number): Promise<void> {
         const args: string[] = ["pm", "install-abandon", sessionId.toString()];
         const output = await this.adb.subprocess
             .spawnAndWaitLegacy(args)
@@ -601,7 +630,7 @@ export class PackageManagerInstallSession {
     static async create(
         packageManager: PackageManager,
         options?: Partial<PackageManagerInstallOptions>,
-    ) {
+    ): Promise<PackageManagerInstallSession> {
         const id = await packageManager.sessionCreate(options);
         return new PackageManagerInstallSession(packageManager, id);
     }
@@ -609,7 +638,7 @@ export class PackageManagerInstallSession {
     #packageManager: PackageManager;
 
     #id: number;
-    get id() {
+    get id(): number {
         return this.#id;
     }
 
@@ -618,15 +647,15 @@ export class PackageManagerInstallSession {
         this.#id = id;
     }
 
-    addSplit(splitName: string, path: string) {
+    addSplit(splitName: string, path: string): Promise<void> {
         return this.#packageManager.sessionAddSplit(this.#id, splitName, path);
     }
 
     addSplitStream(
         splitName: string,
         size: number,
-        stream: ReadableStream<Consumable<Uint8Array>>,
-    ) {
+        stream: ReadableStream<MaybeConsumable<Uint8Array>>,
+    ): Promise<void> {
         return this.#packageManager.sessionAddSplitStream(
             this.#id,
             splitName,
@@ -635,11 +664,11 @@ export class PackageManagerInstallSession {
         );
     }
 
-    commit() {
+    commit(): Promise<void> {
         return this.#packageManager.sessionCommit(this.#id);
     }
 
-    abandon() {
+    abandon(): Promise<void> {
         return this.#packageManager.sessionAbandon(this.#id);
     }
 }

package/src/settings.ts

@@ -66,7 +66,7 @@ export class Settings extends AdbCommandBase {
         namespace: SettingsNamespace,
         key: string,
         options?: SettingsOptions,
-    ) {
+    ): Promise<string> {
         const output = await this.base("get", namespace, options, key);
         // Remove last \n
         return output.substring(0, output.length - 1);

package/src/string-format.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-argument */
 export class ParseError extends Error {
     #expected: string[];
 
@@ -94,7 +93,7 @@ export const p = {
                     const result = format.stringify(value);
                     // Parse the result to make sure it is valid
                     format.parse({ value: result, position: 0 });
-                } catch (e) {
+                } catch {
                     // ignore
                 }
             }
@@ -104,8 +103,7 @@ export const p = {
     separated: <T>(
         separator: string,
         format: Format<T>,
-        min = 0,
-        max = Infinity,
+        { min = 0, max = Infinity }: { min?: number; max?: number } = {},
     ): Format<T[]> => ({
         parse(reader: Reader) {
             const result: T[] = [];
@@ -143,7 +141,7 @@ export const p = {
             while (true) {
                 try {
                     result.push(format.parse(reader));
-                } catch (e) {
+                } catch {
                     break;
                 }
             }

package/tsconfig.build.json

@@ -9,6 +9,6 @@
         },
         {
             "path": "../struct/tsconfig.build.json"
-        },
+        }
     ]
 }