@yume-chan/adb 1.0.0 → 2.0.0

package/esm/commands/subprocess/protocols/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/commands/subprocess/protocols/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EACR,eAAe,EACf,cAAc,EACd,cAAc,EACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5D;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/B;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAE3D;;OAEG;IACH,IAAI,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gCAAgC;IAC7C,+DAA+D;IAC/D,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAEjD,sDAAsD;IACtD,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC,qBAAqB,CAAC,CAAC;IAExE,gDAAgD;IAChD,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC,qBAAqB,CAAC,CAAC;IAExE,oEAAoE;IACpE,KAAK,MAAM,EAAE,SAAS,GAAG,qBAAqB,CAAC;CAClD"}

package/esm/commands/subprocess/protocols/types.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.js.map

package/esm/commands/subprocess/protocols/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/commands/subprocess/protocols/types.ts"],"names":[],"mappings":""}

package/src/commands/subprocess/command.ts

@@ -1,141 +0,0 @@
-import { ConcatStringStream, TextDecoderStream } from "@yume-chan/stream-extra";
-
-import { AdbCommandBase } from "../base.js";
-
-import type {
-    AdbSubprocessProtocol,
-    AdbSubprocessProtocolConstructor,
-} from "./protocols/index.js";
-import {
-    AdbSubprocessNoneProtocol,
-    AdbSubprocessShellProtocol,
-} from "./protocols/index.js";
-
-export interface AdbSubprocessOptions {
-    /**
-     * A list of `AdbSubprocessProtocolConstructor`s to be used.
-     *
-     * Different `AdbSubprocessProtocol` has different capabilities, thus requires specific adaptations.
-     * Check their documentations for details.
-     *
-     * The first protocol whose `isSupported` returns `true` will be used.
-     * If no `AdbSubprocessProtocol` is supported, an error will be thrown.
-     *
-     * @default [AdbSubprocessShellProtocol, AdbSubprocessNoneProtocol]
-     */
-    protocols: AdbSubprocessProtocolConstructor[];
-}
-
-const DEFAULT_OPTIONS: AdbSubprocessOptions = {
-    protocols: [AdbSubprocessShellProtocol, AdbSubprocessNoneProtocol],
-};
-
-export interface AdbSubprocessWaitResult {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-}
-
-export class AdbSubprocess extends AdbCommandBase {
-    async #createProtocol(
-        mode: "pty" | "raw",
-        command?: string | string[],
-        options?: Partial<AdbSubprocessOptions>,
-    ): Promise<AdbSubprocessProtocol> {
-        const { protocols } = { ...DEFAULT_OPTIONS, ...options };
-
-        let Constructor: AdbSubprocessProtocolConstructor | undefined;
-        for (const item of protocols) {
-            // It's async so can't use `Array#find`
-            if (await item.isSupported(this.adb)) {
-                Constructor = item;
-                break;
-            }
-        }
-
-        if (!Constructor) {
-            throw new Error("No specified protocol is supported by the device");
-        }
-
-        if (Array.isArray(command)) {
-            command = command.join(" ");
-        } else if (command === undefined) {
-            // spawn the default shell
-            command = "";
-        }
-        return await Constructor[mode](this.adb, command);
-    }
-
-    /**
-     * Spawns an executable in PTY mode.
-     *
-     * Redirection mode is enough for most simple commands, but PTY mode is required for
-     * commands that manipulate the terminal, such as `vi` and `less`.
-     * @param command The command to run. If omitted, the default shell will be spawned.
-     * @param options The options for creating the `AdbSubprocessProtocol`
-     * @returns A new `AdbSubprocessProtocol` instance connecting to the spawned process.
-     */
-    shell(
-        command?: string | string[],
-        options?: Partial<AdbSubprocessOptions>,
-    ): Promise<AdbSubprocessProtocol> {
-        return this.#createProtocol("pty", command, options);
-    }
-
-    /**
-     * Spawns an executable and redirect the standard input/output stream.
-     *
-     * Redirection mode is enough for most simple commands, but PTY mode is required for
-     * commands that manipulate the terminal, such as `vi` and `less`.
-     * @param command The command to run, or an array of strings containing both command and args.
-     * @param options The options for creating the `AdbSubprocessProtocol`
-     * @returns A new `AdbSubprocessProtocol` instance connecting to the spawned process.
-     */
-    spawn(
-        command: string | string[],
-        options?: Partial<AdbSubprocessOptions>,
-    ): Promise<AdbSubprocessProtocol> {
-        return this.#createProtocol("raw", command, options);
-    }
-
-    /**
-     * Spawns a new process, waits until it exits, and returns the entire output.
-     * @param command The command to run
-     * @param options The options for creating the `AdbSubprocessProtocol`
-     * @returns The entire output of the command
-     */
-    async spawnAndWait(
-        command: string | string[],
-        options?: Partial<AdbSubprocessOptions>,
-    ): Promise<AdbSubprocessWaitResult> {
-        const process = await this.spawn(command, options);
-
-        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,
-        };
-    }
-
-    /**
-     * Spawns a new process, waits until it exits, and returns the entire output.
-     * @param command The command to run
-     * @returns The entire output of the command
-     */
-    async spawnAndWaitLegacy(command: string | string[]): Promise<string> {
-        const { stdout } = await this.spawnAndWait(command, {
-            protocols: [AdbSubprocessNoneProtocol],
-        });
-        return stdout;
-    }
-}

package/src/commands/subprocess/protocols/index.ts

@@ -1,3 +0,0 @@
-export * from "./none.js";
-export * from "./shell.js";
-export * from "./types.js";

package/src/commands/subprocess/protocols/none.ts

@@ -1,81 +0,0 @@
-import type { MaybeConsumable, WritableStream } from "@yume-chan/stream-extra";
-import { ReadableStream } from "@yume-chan/stream-extra";
-
-import type { Adb, AdbSocket } from "../../../adb.js";
-
-import type { AdbSubprocessProtocol } from "./types.js";
-
-/**
- * The legacy shell
- *
- * Features:
- * * `stderr`: No
- * * `exit` exit code: No
- * * `resize`: No
- */
-export class AdbSubprocessNoneProtocol implements AdbSubprocessProtocol {
-    static isSupported() {
-        return true;
-    }
-
-    static async pty(adb: Adb, command: string) {
-        return new AdbSubprocessNoneProtocol(
-            await adb.createSocket(`shell:${command}`),
-        );
-    }
-
-    static async raw(adb: Adb, command: string) {
-        // `shell,raw:${command}` also triggers raw mode,
-        // But is not supported on Android version <7.
-        return new AdbSubprocessNoneProtocol(
-            await adb.createSocket(`exec:${command}`),
-        );
-    }
-
-    readonly #socket: AdbSocket;
-
-    // Legacy shell forwards all data to stdin.
-    get stdin(): WritableStream<MaybeConsumable<Uint8Array>> {
-        return this.#socket.writable;
-    }
-
-    /**
-     * Legacy shell mixes stdout and stderr.
-     */
-    get stdout(): ReadableStream<Uint8Array> {
-        return this.#socket.readable;
-    }
-
-    #stderr: ReadableStream<Uint8Array>;
-    /**
-     * `stderr` will always be empty.
-     */
-    get stderr(): ReadableStream<Uint8Array> {
-        return this.#stderr;
-    }
-
-    #exit: Promise<number>;
-    get exit() {
-        return this.#exit;
-    }
-
-    constructor(socket: AdbSocket) {
-        this.#socket = socket;
-
-        this.#stderr = new ReadableStream({
-            start: async (controller) => {
-                await this.#socket.closed;
-                controller.close();
-            },
-        });
-        this.#exit = socket.closed.then(() => 0);
-    }
-
-    resize() {
-        // Not supported, but don't throw.
-    }
-
-    async kill() {
-        await this.#socket.close();
-    }
-}

package/src/commands/subprocess/protocols/shell.ts

@@ -1,171 +0,0 @@
-import { PromiseResolver } from "@yume-chan/async";
-import type {
-    PushReadableStreamController,
-    ReadableStream,
-    WritableStreamDefaultWriter,
-} from "@yume-chan/stream-extra";
-import {
-    MaybeConsumable,
-    PushReadableStream,
-    StructDeserializeStream,
-    WritableStream,
-} from "@yume-chan/stream-extra";
-import type { StructValue } from "@yume-chan/struct";
-import { buffer, struct, u32, u8 } from "@yume-chan/struct";
-
-import type { Adb, AdbSocket } from "../../../adb.js";
-import { AdbFeature } from "../../../features.js";
-import { encodeUtf8 } from "../../../utils/index.js";
-
-import type { AdbSubprocessProtocol } from "./types.js";
-
-export const AdbShellProtocolId = {
-    Stdin: 0,
-    Stdout: 1,
-    Stderr: 2,
-    Exit: 3,
-    CloseStdin: 4,
-    WindowSizeChange: 5,
-} as const;
-
-export type AdbShellProtocolId =
-    (typeof AdbShellProtocolId)[keyof typeof AdbShellProtocolId];
-
-// This packet format is used in both directions.
-export const AdbShellProtocolPacket = struct(
-    {
-        id: u8<AdbShellProtocolId>(),
-        data: buffer(u32),
-    },
-    { littleEndian: true },
-);
-
-type AdbShellProtocolPacket = StructValue<typeof AdbShellProtocolPacket>;
-
-/**
- * Shell v2 a.k.a Shell Protocol
- *
- * Features:
- * * `stderr`: Yes
- * * `exit` exit code: Yes
- * * `resize`: Yes
- */
-export class AdbSubprocessShellProtocol implements AdbSubprocessProtocol {
-    static isSupported(adb: Adb) {
-        return adb.canUseFeature(AdbFeature.ShellV2);
-    }
-
-    static async pty(adb: Adb, command: string) {
-        // TODO: AdbShellSubprocessProtocol: Support setting `XTERM` environment variable
-        return new AdbSubprocessShellProtocol(
-            await adb.createSocket(`shell,v2,pty:${command}`),
-        );
-    }
-
-    static async raw(adb: Adb, command: string) {
-        return new AdbSubprocessShellProtocol(
-            await adb.createSocket(`shell,v2,raw:${command}`),
-        );
-    }
-
-    readonly #socket: AdbSocket;
-    #writer: WritableStreamDefaultWriter<MaybeConsumable<Uint8Array>>;
-
-    #stdin: WritableStream<MaybeConsumable<Uint8Array>>;
-    get stdin() {
-        return this.#stdin;
-    }
-
-    #stdout: ReadableStream<Uint8Array>;
-    get stdout() {
-        return this.#stdout;
-    }
-
-    #stderr: ReadableStream<Uint8Array>;
-    get stderr() {
-        return this.#stderr;
-    }
-
-    readonly #exit = new PromiseResolver<number>();
-    get exit() {
-        return this.#exit.promise;
-    }
-
-    constructor(socket: AdbSocket) {
-        this.#socket = socket;
-
-        let stdoutController!: PushReadableStreamController<Uint8Array>;
-        let stderrController!: PushReadableStreamController<Uint8Array>;
-        this.#stdout = new PushReadableStream<Uint8Array>((controller) => {
-            stdoutController = controller;
-        });
-        this.#stderr = new PushReadableStream<Uint8Array>((controller) => {
-            stderrController = controller;
-        });
-
-        socket.readable
-            .pipeThrough(new StructDeserializeStream(AdbShellProtocolPacket))
-            .pipeTo(
-                new WritableStream<AdbShellProtocolPacket>({
-                    write: async (chunk) => {
-                        switch (chunk.id) {
-                            case AdbShellProtocolId.Exit:
-                                this.#exit.resolve(chunk.data[0]!);
-                                break;
-                            case AdbShellProtocolId.Stdout:
-                                await stdoutController.enqueue(chunk.data);
-                                break;
-                            case AdbShellProtocolId.Stderr:
-                                await stderrController.enqueue(chunk.data);
-                                break;
-                        }
-                    },
-                }),
-            )
-            .then(
-                () => {
-                    stdoutController.close();
-                    stderrController.close();
-                    // If `#exit` has already resolved, this will be a no-op
-                    this.#exit.reject(
-                        new Error("Socket ended without exit message"),
-                    );
-                },
-                (e) => {
-                    stdoutController.error(e);
-                    stderrController.error(e);
-                    // If `#exit` has already resolved, this will be a no-op
-                    this.#exit.reject(e);
-                },
-            );
-
-        this.#writer = this.#socket.writable.getWriter();
-
-        this.#stdin = new MaybeConsumable.WritableStream<Uint8Array>({
-            write: async (chunk) => {
-                await this.#writer.write(
-                    AdbShellProtocolPacket.serialize({
-                        id: AdbShellProtocolId.Stdin,
-                        data: chunk,
-                    }),
-                );
-            },
-        });
-    }
-
-    async resize(rows: number, cols: number) {
-        await this.#writer.write(
-            AdbShellProtocolPacket.serialize({
-                id: AdbShellProtocolId.WindowSizeChange,
-                // The "correct" format is `${rows}x${cols},${x_pixels}x${y_pixels}`
-                // However, according to https://linux.die.net/man/4/tty_ioctl
-                // `x_pixels` and `y_pixels` are unused, so always sending `0` should be fine.
-                data: encodeUtf8(`${rows}x${cols},0x0\0`),
-            }),
-        );
-    }
-
-    kill() {
-        return this.#socket.close();
-    }
-}

package/src/commands/subprocess/protocols/types.ts

@@ -1,63 +0,0 @@
-import type { MaybePromiseLike } from "@yume-chan/async";
-import type {
-    MaybeConsumable,
-    ReadableStream,
-    WritableStream,
-} from "@yume-chan/stream-extra";
-
-import type { Adb, AdbSocket } from "../../../adb.js";
-
-export interface AdbSubprocessProtocol {
-    /**
-     * A WritableStream that writes to the `stdin` stream.
-     */
-    readonly stdin: WritableStream<MaybeConsumable<Uint8Array>>;
-
-    /**
-     * The `stdout` stream of the process.
-     */
-    readonly stdout: ReadableStream<Uint8Array>;
-
-    /**
-     * The `stderr` stream of the process.
-     *
-     * Note: Some `AdbSubprocessProtocol` doesn't separate `stdout` and `stderr`,
-     * All output will be sent to `stdout`.
-     */
-    readonly stderr: ReadableStream<Uint8Array>;
-
-    /**
-     * A `Promise` that resolves to the exit code of the process.
-     *
-     * Note: Some `AdbSubprocessProtocol` doesn't support exit code,
-     * They will always resolve it with `0`.
-     */
-    readonly exit: Promise<number>;
-
-    /**
-     * Resizes the current shell.
-     *
-     * Some `AdbSubprocessProtocol`s may not support resizing
-     * and will ignore calls to this method.
-     */
-    resize(rows: number, cols: number): MaybePromiseLike<void>;
-
-    /**
-     * Kills the current process.
-     */
-    kill(): MaybePromiseLike<void>;
-}
-
-export interface AdbSubprocessProtocolConstructor {
-    /** Returns `true` if the `adb` instance supports this shell */
-    isSupported(adb: Adb): MaybePromiseLike<boolean>;
-
-    /** Spawns an executable in PTY (interactive) mode. */
-    pty(adb: Adb, command: string): MaybePromiseLike<AdbSubprocessProtocol>;
-
-    /** Spawns an executable and pipe the output. */
-    raw(adb: Adb, command: string): MaybePromiseLike<AdbSubprocessProtocol>;
-
-    /** Creates a new `AdbShell` by attaching to an exist `AdbSocket` */
-    new (socket: AdbSocket): AdbSubprocessProtocol;
-}