autojs6-mcp-bridge 0.1.0

package/README.md

@@ -0,0 +1,163 @@
+# autojs6-mcp-bridge
+
+Language: English | [简体中文](README-zh-Hans.md)
+
+A small stdio to Streamable HTTP bridge for the
+[AutoJs6 MCP Server plugin](https://github.com/SuperMonster003/AutoJs6-Plugin-MCP-Server).
+MCP clients that can only launch stdio servers (Claude Desktop, older Cursor and
+Cline builds, anything without an HTTP transport) start this program; it forwards
+every JSON-RPC message to the phone over HTTP and returns the answers.
+
+The bridge does not add tools, permissions or state of its own. The token and
+the phone-side pairing of the plugin still apply, and the phone still asks you
+to allow each new client.
+
+## Requirements
+
+- Node.js 18 or newer.
+- The AutoJs6 MCP Server plugin switched on in the AutoJs6 drawer, and its
+  token copied from the plugin settings page.
+- For USB: Android platform-tools (`adb`) on the PATH or passed with `--adb`.
+
+## Install
+
+```shell
+npm install -g autojs6-mcp-bridge
+autojs6-mcp-bridge --version
+```
+
+`npx autojs6-mcp-bridge` works too, but clients start the bridge on every
+session, so a global install keeps startup fast.
+
+## Usage
+
+```text
+autojs6-mcp-bridge [options]
+
+  --url <url>          Endpoint of the phone (default: http://127.0.0.1:9637/mcp)
+  --serial <serial>    Run "adb -s <serial> forward" for the endpoint port and remove it on exit
+  --forward            Run "adb forward" without -s (single device or emulator)
+  --adb <path>         adb executable (default: adb on the PATH, or AUTOJS6_MCP_ADB)
+  --protocol <date>    Request this MCP protocol version from the phone instead of the client's
+  --token <token>      Bearer token; prefer the AUTOJS6_MCP_TOKEN environment variable
+  -h, --help           Show this help
+  -v, --version        Show the version
+```
+
+The token is read from `AUTOJS6_MCP_TOKEN` first so that it does not appear in
+process listings; `--token` is accepted for one-off use and prints a warning.
+`--serial` and `--forward` require a loopback `--url`; over Wi-Fi pass the
+address shown on the plugin settings page and leave forwarding off.
+
+## Client configuration
+
+The plugin settings page copies the HTTP configuration for clients that
+support it. For stdio-only clients, point them at this bridge instead.
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "autojs6": {
+      "command": "autojs6-mcp-bridge",
+      "args": ["--serial", "<serial from adb devices>"],
+      "env": {
+        "AUTOJS6_MCP_TOKEN": "<token>"
+      }
+    }
+  }
+}
+```
+
+Claude Code (stdio fallback when the HTTP transport cannot be used):
+
+```shell
+claude mcp add autojs6 -e AUTOJS6_MCP_TOKEN=<token> -- autojs6-mcp-bridge --serial <serial>
+```
+
+Any other stdio client: command `autojs6-mcp-bridge`, arguments as above, and
+`AUTOJS6_MCP_TOKEN` in the environment block of its configuration. Over Wi-Fi
+replace `--serial <serial>` with `--url http://<phone-address>:9637/mcp`.
+
+## How it works
+
+- The client's stdin / stdout carry newline-delimited JSON-RPC (the MCP stdio
+  transport); the bridge uses the official MCP SDK transports on both sides.
+- Each message is POSTed to the phone with `Authorization: Bearer <token>`,
+  the `Mcp-Session-Id` returned by the phone and the negotiated
+  `MCP-Protocol-Version`. Responses arrive as JSON or as SSE and are written
+  back to stdout unchanged. The phone's own errors, such as
+  `PAIRING_REQUIRED` on the first call of a new client, pass through as they
+  are; accept the pairing prompt on the phone and let the client retry.
+- `--protocol <date>` rewrites the `protocolVersion` of the client's
+  `initialize` request. Without it the client's version is passed through and
+  the phone negotiates as usual.
+- With `--serial` or `--forward`, the bridge runs `adb forward tcp:<port>
+  tcp:<port>` before the first request and `adb forward --remove` when the
+  client closes stdin or the process receives SIGINT / SIGTERM. Requests
+  that are still on their way to the phone when stdin ends get up to 10 s
+  to finish, so a one-shot `echo '{...}' | autojs6-mcp-bridge` still
+  receives its answer.
+- The first connection through a forward that was just created can be
+  refused or reset while the phone's listener is coming up; the bridge
+  repeats `initialize` up to 4 times (500 ms apart) before reporting the
+  failure. Later requests are never repeated, because they may have
+  already acted on the phone.
+- When a message cannot be delivered, the client receives a JSON-RPC error
+  (code -32000) with one readable sentence instead of a hanging request:
+
+| Situation | Message starts with |
+| --- | --- |
+| Token rejected | `401 Unauthorized from <url>: the token was rejected. Copy it again ...` |
+| Phone not listening or no forward | `Cannot connect to <url> (connection refused): switch MCP Server on ...` |
+| Phone unreachable over Wi-Fi | `Cannot reach <url> (EHOSTUNREACH): the phone is not reachable on this network ...` |
+| Host header not on the allow list | `421 Misdirected Request from <url>: the Host header is not accepted ...` |
+| Listener restarted | `The connection to <url> was reset: the listener restarted ...` |
+| adb problems at startup | `adb forward tcp:9637 failed (exit 1): ... Several devices are connected: pass --serial ...` (exit code 3) |
+
+Exit codes: 0 on a normal close, 1 on an unexpected error, 2 for invalid
+options, 3 when `adb forward` fails.
+
+## Compatibility
+
+| Bridge | Plugin | MCP protocol requested by the bridge | Node.js | Verified clients |
+| --- | --- | --- | --- | --- |
+| 0.1.0 | AutoJs6 MCP Server 1.0.0 | passes the client's version through (the plugin negotiates 2025-06-18 or older); `--protocol` overrides it | 18 or newer (`engines`); tested with 24.15 | Claude Code 2.1.257 (stdio, `claude mcp add ... -- autojs6-mcp-bridge --serial <serial>`) |
+
+Keep this table in step with the plugin README; both sides list it.
+
+## Security
+
+- The token authorizes full control of the phone through the plugin. Keep it
+  in the environment block of the client configuration, not in shell history
+  or process arguments, and rotate it from the plugin settings page if it
+  leaks.
+- The bridge talks plain HTTP to the phone. Over USB the traffic stays on the
+  adb forward; over Wi-Fi use a trusted network and the addresses listed on
+  the plugin settings page.
+- Only stderr carries diagnostics; stdout is reserved for the protocol. The
+  token is never logged.
+
+## Development
+
+```shell
+npm install
+npm test          # builds dist/ and runs node --test
+npm run pack:check
+```
+
+Tests cover option parsing, the adb forward lifecycle with a fake runner,
+the error mapping, and the message flow against a local fake phone (protocol
+passthrough and rewrite, session id and protocol headers, 401 and connection
+refused mapping, session termination on close).
+
+## License
+
+[Mozilla Public License 2.0](LICENSE).
+
+## Links
+
+- Plugin: https://github.com/SuperMonster003/AutoJs6-Plugin-MCP-Server
+- AutoJs6: https://github.com/SuperMonster003/AutoJs6
+- MCP specification: https://modelcontextprotocol.io/specification

package/dist/bridge.d.ts

@@ -0,0 +1,65 @@
+import type { Readable, Writable } from 'node:stream';
+import type { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js';
+/** How long a closing bridge waits for requests that are still on their way to the phone. */
+export declare const DRAIN_TIMEOUT_MS = 10000;
+/** Attempts for the initialize request while the phone's listener is still coming up. */
+export declare const INITIALIZE_ATTEMPTS = 4;
+export declare const INITIALIZE_RETRY_DELAY_MS = 500;
+/** True for connection-level failures that happen before the phone has seen the request. */
+export declare function isRetryableConnectionError(error: unknown): boolean;
+export interface BridgeConfig {
+    /** Streamable HTTP endpoint of the phone. */
+    url: URL;
+    /** Bearer token for the Authorization header. */
+    token: string;
+    /** Protocol version to request instead of the client's; undefined passes the client's through. */
+    protocol?: string;
+    /** stdio side; defaults to the process streams. */
+    input?: Readable;
+    output?: Writable;
+    /** Diagnostics sink; defaults to stderr. Never write to stdout, it carries the protocol. */
+    log?: (line: string) => void;
+    /** Custom fetch for tests. */
+    fetch?: FetchLike;
+    /** Extra headers for every request, for example a User-Agent. */
+    headers?: Record<string, string>;
+}
+/**
+ * Moves JSON-RPC messages between a stdio client and the phone's Streamable HTTP endpoint. The
+ * SDK transports own framing, the Bearer header, the session id and the SSE stream; the bridge
+ * only rewrites the requested protocol version when asked, records the negotiated version for the
+ * MCP-Protocol-Version header, and answers requests that could not be delivered with a readable
+ * JSON-RPC error instead of leaving the client waiting.
+ */
+export declare class Bridge {
+    private readonly stdio;
+    private readonly http;
+    private readonly input;
+    private readonly log;
+    private readonly url;
+    private readonly protocol?;
+    private initializeId;
+    private closed;
+    private inflight;
+    private idle;
+    /** Resolves when the client side closes (stdin ends) or `close` is called. */
+    readonly done: Promise<void>;
+    private finish;
+    constructor(config: BridgeConfig);
+    /** The session id assigned by the phone after initialize, if any. */
+    get sessionId(): string | undefined;
+    /** The protocol version negotiated with the phone, if initialize has completed. */
+    get protocolVersion(): string | undefined;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private toPhone;
+    /**
+     * `initialize` is the first request of a session and safe to repeat: when the listener has
+     * just been switched on (or restarted after a port change), the first connection through adb
+     * can be refused or reset, so it is retried a few times before the client is told.
+     */
+    private sendWithRetry;
+    /** Resolves when no request is in flight, or after [timeoutMs] at the latest. */
+    private settle;
+    private toClient;
+}

package/dist/bridge.js

@@ -0,0 +1,186 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { isInitializeRequest, isJSONRPCRequest, isJSONRPCResponse } from '@modelcontextprotocol/sdk/types.js';
+import { BRIDGE_ERROR_CODE, describeError } from './errors.js';
+/** How long a closing bridge waits for requests that are still on their way to the phone. */
+export const DRAIN_TIMEOUT_MS = 10_000;
+/** Attempts for the initialize request while the phone's listener is still coming up. */
+export const INITIALIZE_ATTEMPTS = 4;
+export const INITIALIZE_RETRY_DELAY_MS = 500;
+const RETRYABLE_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'UND_ERR_SOCKET', 'EPIPE']);
+/** True for connection-level failures that happen before the phone has seen the request. */
+export function isRetryableConnectionError(error) {
+    let current = error;
+    for (let depth = 0; depth < 4 && current && typeof current === 'object'; depth += 1) {
+        const code = current.code;
+        if (typeof code === 'string' && RETRYABLE_CODES.has(code)) {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * Moves JSON-RPC messages between a stdio client and the phone's Streamable HTTP endpoint. The
+ * SDK transports own framing, the Bearer header, the session id and the SSE stream; the bridge
+ * only rewrites the requested protocol version when asked, records the negotiated version for the
+ * MCP-Protocol-Version header, and answers requests that could not be delivered with a readable
+ * JSON-RPC error instead of leaving the client waiting.
+ */
+export class Bridge {
+    stdio;
+    http;
+    input;
+    log;
+    url;
+    protocol;
+    initializeId;
+    closed = false;
+    inflight = 0;
+    idle = [];
+    /** Resolves when the client side closes (stdin ends) or `close` is called. */
+    done;
+    finish;
+    constructor(config) {
+        this.url = config.url;
+        this.protocol = config.protocol;
+        this.log = config.log ?? (line => process.stderr.write(`${line}\n`));
+        this.input = config.input ?? process.stdin;
+        this.stdio = new StdioServerTransport(this.input, config.output ?? process.stdout);
+        this.http = new StreamableHTTPClientTransport(config.url, {
+            fetch: config.fetch,
+            requestInit: { headers: { Authorization: `Bearer ${config.token}`, ...(config.headers ?? {}) } }
+        });
+        this.done = new Promise(resolve => {
+            this.finish = resolve;
+        });
+    }
+    /** The session id assigned by the phone after initialize, if any. */
+    get sessionId() {
+        return this.http.sessionId;
+    }
+    /** The protocol version negotiated with the phone, if initialize has completed. */
+    get protocolVersion() {
+        return this.http.protocolVersion;
+    }
+    async start() {
+        this.stdio.onmessage = message => {
+            void this.toPhone(message);
+        };
+        this.stdio.onerror = error => this.log(`client transport error: ${error.message}`);
+        this.stdio.onclose = () => {
+            void this.close();
+        };
+        this.http.onmessage = message => {
+            void this.toClient(message);
+        };
+        this.http.onerror = error => this.log(`phone transport error: ${describeError(error, this.url)}`);
+        this.http.onclose = () => this.log('phone transport closed');
+        // The SDK's stdio server transport does not watch for the end of stdin; a client that exits
+        // closes our stdin, and that must end the bridge (and remove the adb forward). Requests that
+        // are still on their way to the phone get a bounded grace period so that piped one-shot
+        // invocations still receive their answer.
+        const ended = () => {
+            void this.settle(DRAIN_TIMEOUT_MS).then(() => this.close());
+        };
+        this.input.once('end', ended);
+        this.input.once('close', ended);
+        await this.http.start();
+        await this.stdio.start();
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        try {
+            if (this.http.sessionId) {
+                await this.http.terminateSession();
+            }
+        }
+        catch {
+            // The phone may not support DELETE; the session expires on its own.
+        }
+        await this.http.close().catch(() => undefined);
+        await this.stdio.close().catch(() => undefined);
+        this.finish();
+    }
+    async toPhone(incoming) {
+        let message = incoming;
+        if (isJSONRPCRequest(message) && isInitializeRequest(message)) {
+            this.initializeId = message.id;
+            if (this.protocol && message.params.protocolVersion !== this.protocol) {
+                this.log(`requesting protocol ${this.protocol} instead of ${message.params.protocolVersion}`);
+                message = { ...message, params: { ...message.params, protocolVersion: this.protocol } };
+            }
+        }
+        this.inflight += 1;
+        try {
+            await this.sendWithRetry(message);
+        }
+        catch (error) {
+            const description = describeError(error, this.url);
+            this.log(description);
+            if (isJSONRPCRequest(message)) {
+                await this.stdio
+                    .send({ jsonrpc: '2.0', id: message.id, error: { code: BRIDGE_ERROR_CODE, message: description } })
+                    .catch(sendError => this.log(`cannot answer the client: ${String(sendError)}`));
+            }
+        }
+        finally {
+            this.inflight -= 1;
+            if (this.inflight === 0) {
+                this.idle.splice(0).forEach(resolve => resolve());
+            }
+        }
+    }
+    /**
+     * `initialize` is the first request of a session and safe to repeat: when the listener has
+     * just been switched on (or restarted after a port change), the first connection through adb
+     * can be refused or reset, so it is retried a few times before the client is told.
+     */
+    async sendWithRetry(message) {
+        const attempts = isInitializeRequest(message) ? INITIALIZE_ATTEMPTS : 1;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await this.http.send(message);
+                return;
+            }
+            catch (error) {
+                if (attempt >= attempts || this.closed || !isRetryableConnectionError(error)) {
+                    throw error;
+                }
+                this.log(`initialize attempt ${attempt} failed (${describeError(error, this.url)}); retrying in ${INITIALIZE_RETRY_DELAY_MS} ms`);
+                await new Promise(resolve => setTimeout(resolve, INITIALIZE_RETRY_DELAY_MS));
+            }
+        }
+    }
+    /** Resolves when no request is in flight, or after [timeoutMs] at the latest. */
+    settle(timeoutMs) {
+        if (this.inflight === 0) {
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            const timer = setTimeout(resolve, timeoutMs);
+            this.idle.push(() => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    async toClient(message) {
+        if (this.initializeId !== undefined && isJSONRPCResponse(message) && message.id === this.initializeId) {
+            const version = message.result.protocolVersion;
+            if (typeof version === 'string') {
+                this.http.setProtocolVersion(version);
+            }
+            this.initializeId = undefined;
+        }
+        try {
+            await this.stdio.send(message);
+        }
+        catch (error) {
+            this.log(`cannot write to the client: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { Bridge } from './bridge.js';
+import { AdbForward, AdbForwardError } from './forward.js';
+import { endpointPort, OptionError, parseOptions, USAGE } from './options.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+function log(line) {
+    process.stderr.write(`[autojs6-mcp-bridge] ${line}\n`);
+}
+async function main() {
+    let command;
+    try {
+        command = parseOptions(process.argv.slice(2), process.env);
+    }
+    catch (error) {
+        if (error instanceof OptionError) {
+            process.stderr.write(`${error.message}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    if (command.kind === 'help') {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (command.kind === 'version') {
+        process.stdout.write(`${version}\n`);
+        return 0;
+    }
+    const { options } = command;
+    options.warnings.forEach(log);
+    const forward = options.forward ? new AdbForward(options.adb, endpointPort(options.url), options.serial) : undefined;
+    if (forward) {
+        try {
+            await forward.start();
+            log(`adb forward ${forward.spec} active${options.serial ? ` for ${options.serial}` : ''}`);
+        }
+        catch (error) {
+            if (error instanceof AdbForwardError) {
+                process.stderr.write(`${error.message}\n`);
+                return 3;
+            }
+            throw error;
+        }
+    }
+    const bridge = new Bridge({
+        url: options.url,
+        token: options.token,
+        protocol: options.protocol,
+        log,
+        headers: { 'User-Agent': `autojs6-mcp-bridge/${version}` }
+    });
+    let exiting = false;
+    const shutdown = async () => {
+        if (exiting) {
+            return;
+        }
+        exiting = true;
+        await bridge.close();
+        await forward?.stop();
+    };
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    await bridge.start();
+    log(`bridging stdio to ${options.url}`);
+    await bridge.done;
+    await shutdown();
+    return 0;
+}
+main().then(code => {
+    process.exitCode = code;
+}, error => {
+    process.stderr.write(`[autojs6-mcp-bridge] ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+/** JSON-RPC error code the bridge uses for transport failures it reports on behalf of the phone. */
+export declare const BRIDGE_ERROR_CODE = -32000;
+/**
+ * Turns a transport failure into one readable sentence for the client (and the log). The phone's
+ * own JSON-RPC errors such as PAIRING_REQUIRED never pass through here; they are forwarded as-is.
+ */
+export declare function describeError(error: unknown, url: URL): string;

package/dist/errors.js

@@ -0,0 +1,62 @@
+import { StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+/** JSON-RPC error code the bridge uses for transport failures it reports on behalf of the phone. */
+export const BRIDGE_ERROR_CODE = -32000;
+/**
+ * Turns a transport failure into one readable sentence for the client (and the log). The phone's
+ * own JSON-RPC errors such as PAIRING_REQUIRED never pass through here; they are forwarded as-is.
+ */
+export function describeError(error, url) {
+    const endpoint = url.toString();
+    if (error instanceof StreamableHTTPError || error instanceof UnauthorizedError) {
+        const code = error instanceof StreamableHTTPError ? error.code : 401;
+        switch (code) {
+            case 401:
+                return `401 Unauthorized from ${endpoint}: the token was rejected. Copy it again from the plugin settings page (Show token) and set AUTOJS6_MCP_TOKEN; a rotated token invalidates the old one.`;
+            case 403:
+                return `403 Forbidden from ${endpoint}: the request was refused by the plugin's allow list. Use a loopback URL over adb forward, or an address listed on the settings page when local network access is on.`;
+            case 404:
+                return `404 Not Found from ${endpoint}: the endpoint path is wrong; the plugin serves /mcp.`;
+            case 421:
+                return `421 Misdirected Request from ${endpoint}: the Host header is not accepted; use the address exactly as shown on the plugin settings page.`;
+            case 429:
+                return `429 Too Many Requests from ${endpoint}: the plugin is rate limiting this client; wait a moment and retry.`;
+            case 503:
+                return `503 Service Unavailable from ${endpoint}: the plugin is stopping or the host session is not ready; check the AutoJs6 drawer switch.`;
+            default:
+                return `${endpoint} answered with an error${code !== undefined && code >= 0 ? ` (HTTP ${code})` : ''}: ${error.message}`;
+        }
+    }
+    const cause = causeCode(error);
+    switch (cause) {
+        case 'ECONNREFUSED':
+            return `Cannot connect to ${endpoint} (connection refused): switch MCP Server on in the AutoJs6 drawer; over USB also run adb forward (use --serial to let the bridge do it).`;
+        case 'ETIMEDOUT':
+        case 'EHOSTUNREACH':
+        case 'ENETUNREACH':
+            return `Cannot reach ${endpoint} (${cause}): the phone is not reachable on this network. Keep the PC and the phone on the same Wi-Fi without guest isolation, enable local network access on the settings page, and allow the port through the firewall.`;
+        case 'ENOTFOUND':
+        case 'EAI_AGAIN':
+            return `Cannot resolve the host of ${endpoint}: use the IP address shown on the plugin settings page.`;
+        case 'ECONNRESET':
+        case 'UND_ERR_SOCKET':
+            return `The connection to ${endpoint} was reset: the listener restarted (port or network change) or the phone dropped the network; retry the request.`;
+        default:
+            break;
+    }
+    if (error instanceof Error) {
+        return `Request to ${endpoint} failed: ${error.message}`;
+    }
+    return `Request to ${endpoint} failed: ${String(error)}`;
+}
+function causeCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 4 && current && typeof current === 'object'; depth += 1) {
+        const code = current.code;
+        if (typeof code === 'string') {
+            return code;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}

package/dist/forward.d.ts

@@ -0,0 +1,27 @@
+export interface CommandResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs an executable with arguments; injected in tests. */
+export type CommandRunner = (command: string, args: readonly string[]) => Promise<CommandResult>;
+export declare const spawnRunner: CommandRunner;
+export declare class AdbForwardError extends Error {
+}
+/**
+ * `adb forward tcp:<port> tcp:<port>` for the lifetime of the bridge. `start` fails with a readable
+ * message when adb is missing, no device is connected, or several devices are connected without
+ * `--serial`; `stop` removes the forward and never throws.
+ */
+export declare class AdbForward {
+    private readonly adb;
+    private readonly port;
+    private readonly serial;
+    private readonly run;
+    private active;
+    constructor(adb: string, port: number, serial: string | undefined, run?: CommandRunner);
+    get args(): string[];
+    get spec(): string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/forward.js

@@ -0,0 +1,82 @@
+import { spawn } from 'node:child_process';
+export const spawnRunner = (command, args) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => {
+        stdout += String(chunk);
+    });
+    child.stderr.on('data', chunk => {
+        stderr += String(chunk);
+    });
+    child.on('error', reject);
+    child.on('close', code => resolve({ code, stdout, stderr }));
+});
+export class AdbForwardError extends Error {
+}
+/**
+ * `adb forward tcp:<port> tcp:<port>` for the lifetime of the bridge. `start` fails with a readable
+ * message when adb is missing, no device is connected, or several devices are connected without
+ * `--serial`; `stop` removes the forward and never throws.
+ */
+export class AdbForward {
+    adb;
+    port;
+    serial;
+    run;
+    active = false;
+    constructor(adb, port, serial, run = spawnRunner) {
+        this.adb = adb;
+        this.port = port;
+        this.serial = serial;
+        this.run = run;
+    }
+    get args() {
+        return this.serial ? ['-s', this.serial] : [];
+    }
+    get spec() {
+        return `tcp:${this.port}`;
+    }
+    async start() {
+        let result;
+        try {
+            result = await this.run(this.adb, [...this.args, 'forward', this.spec, this.spec]);
+        }
+        catch (error) {
+            throw new AdbForwardError(`Cannot run "${this.adb}": ${describe(error)}. Install Android platform-tools and put adb on the PATH, or pass --adb <path>.`);
+        }
+        if (result.code !== 0) {
+            const detail = (result.stderr || result.stdout).trim();
+            let hint = 'Check "adb devices".';
+            if (/more than one device|multiple devices/i.test(detail)) {
+                hint = 'Several devices are connected: pass --serial <serial> from "adb devices".';
+            }
+            else if (/no devices|device '.*' not found|device not found|not found/i.test(detail)) {
+                hint = 'No matching device: connect the phone over USB with USB debugging on and check "adb devices".';
+            }
+            else if (/unauthorized/i.test(detail)) {
+                hint = 'The phone has not authorized this computer: accept the USB debugging prompt on the phone.';
+            }
+            throw new AdbForwardError(`adb forward ${this.spec} failed (exit ${result.code}): ${detail || 'no output'}. ${hint}`);
+        }
+        this.active = true;
+    }
+    async stop() {
+        if (!this.active) {
+            return;
+        }
+        this.active = false;
+        try {
+            await this.run(this.adb, [...this.args, 'forward', '--remove', this.spec]);
+        }
+        catch {
+            // Best effort: a missing adb at shutdown is not worth failing the exit.
+        }
+    }
+}
+function describe(error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+        return 'not found';
+    }
+    return error instanceof Error ? error.message : String(error);
+}