Skip to content

Commit 90193ef

Browse files
committed
fix(android): name the adb host invariant and catch Windows adb without Installed as
The hint fired on every non-win32 host but only advised WSL users; state the invariant that adb must be a native binary for this host and keep WSL as the example. Treat a "Running on Windows" banner as the same signal so builds that omit "Installed as" fail closed instead of passing green, and key the check on detectedVia.
1 parent dbc0161 commit 90193ef

3 files changed

Lines changed: 84 additions & 11 deletions

File tree

‎packages/platform-android/src/__tests__/doctor.test.ts‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,16 @@ const LINUX_ADB_VERSION = [
114114
'Installed as /home/dev/Android/Sdk/platform-tools/adb',
115115
'Running on Linux 6.18.0-microsoft-standard-WSL2 (x86_64)',
116116
].join('\n');
117+
// adb builds before 1.0.36 and some third-party builds omit the `Installed as` banner, leaving the
118+
// `Running on Windows` line as the only signal that the binary is a Windows one.
119+
const WINDOWS_ADB_VERSION_WITHOUT_INSTALL_PATH = [
120+
'Android Debug Bridge version 1.0.39',
121+
'Running on Windows 10.0.26100',
122+
].join('\n');
123+
const LINUX_ADB_VERSION_WITHOUT_INSTALL_PATH = [
124+
'Android Debug Bridge version 1.0.39',
125+
'Running on Linux 6.18.0 (x86_64)',
126+
].join('\n');
117127

118128
async function toolchainCheckWithAdbVersion(
119129
versionOutput: string,
@@ -135,8 +145,32 @@ test('fails the toolchain when adb on a POSIX host is the Windows binary', async
135145
const check = await toolchainCheckWithAdbVersion(WINDOWS_ADB_VERSION);
136146
assert.equal(check.status, 'fail');
137147
assert.equal(check.evidence?.reason, 'android_adb_windows_binary_on_posix_host');
148+
assert.equal(check.evidence?.detectedVia, 'installed-as-path');
138149
assert.equal(check.evidence?.adbPath, WINDOWS_ADB_PATH);
139-
assert.match(check.hint ?? '', /Linux Android platform-tools/);
150+
assert.match(check.summary ?? '', /Windows binary/);
151+
assert.match(check.hint ?? '', /native binary for this host/);
152+
assert.match(check.hint ?? '', /Under WSL/);
153+
});
154+
155+
test('names the invariant in the hint for a non-WSL host reaching a Windows adb', async () => {
156+
const check = await toolchainCheckWithAdbVersion(WINDOWS_ADB_VERSION, 'darwin');
157+
assert.equal(check.status, 'fail');
158+
assert.equal(check.evidence?.detectedVia, 'installed-as-path');
159+
assert.match(check.hint ?? '', /^adb must be a native binary for this host/);
160+
});
161+
162+
test('fails the toolchain from the Running on Windows line when adb omits Installed as', async () => {
163+
const check = await toolchainCheckWithAdbVersion(WINDOWS_ADB_VERSION_WITHOUT_INSTALL_PATH);
164+
assert.equal(check.status, 'fail');
165+
assert.equal(check.evidence?.reason, 'android_adb_windows_binary_on_posix_host');
166+
assert.equal(check.evidence?.detectedVia, 'running-on-line');
167+
assert.equal(check.evidence?.adbPath, null);
168+
});
169+
170+
test('keeps a native binary passing when adb omits Installed as', async () => {
171+
const check = await toolchainCheckWithAdbVersion(LINUX_ADB_VERSION_WITHOUT_INSTALL_PATH);
172+
assert.equal(check.status, 'pass');
173+
assert.equal(check.evidence?.reason, undefined);
140174
});
141175

142176
test('passes the toolchain when adb is the Linux binary, even under WSL', async () => {
@@ -150,3 +184,12 @@ test('passes the toolchain when the Windows binary runs on a Windows host', asyn
150184
assert.equal(check.status, 'pass');
151185
assert.equal(check.evidence?.reason, undefined);
152186
});
187+
188+
test('passes the toolchain on a Windows host when adb only reports Running on Windows', async () => {
189+
const check = await toolchainCheckWithAdbVersion(
190+
WINDOWS_ADB_VERSION_WITHOUT_INSTALL_PATH,
191+
'win32',
192+
);
193+
assert.equal(check.status, 'pass');
194+
assert.equal(check.evidence?.reason, undefined);
195+
});

‎packages/platform-android/src/doctor.ts‎

Lines changed: 39 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,9 @@ export async function androidToolchainCheck(
3737
const versionOutput = await commandOutput('adb', ['version']);
3838
const versionLine = versionOutput === undefined ? undefined : firstOutputLine(versionOutput);
3939
if (!versionOutput || !versionLine) return missingAndroidAdbCheck(sdkRoot, license);
40-
const adbPath = androidAdbInstallPath(versionOutput);
41-
if (hostPlatform !== 'win32' && adbPath && isWindowsHostPath(adbPath)) {
42-
return windowsAdbOnPosixHostCheck({ adbPath, sdkRoot, versionLine });
40+
const windowsAdb = hostPlatform === 'win32' ? undefined : detectWindowsAdb(versionOutput);
41+
if (windowsAdb) {
42+
return windowsAdbOnPosixHostCheck({ windowsAdb, sdkRoot, versionLine });
4343
}
4444

4545
return androidAdbCheck({
@@ -190,21 +190,51 @@ function isWindowsHostPath(candidate: string): boolean {
190190
return /^(?:[A-Za-z]:[\\/]|\\\\)/.test(candidate);
191191
}
192192

193+
/** Banner line naming the OS the running adb was built for; a native host binary never names Windows. */
194+
function reportsWindowsRuntime(versionOutput: string): boolean {
195+
return /^Running on Windows\b/m.test(versionOutput);
196+
}
197+
198+
/** adb's self-report that it is a Windows binary, plus the signal that revealed it. */
199+
type WindowsAdbReport = Readonly<{
200+
detectedVia: 'installed-as-path' | 'running-on-line';
201+
adbPath: string | undefined;
202+
}>;
203+
204+
function detectWindowsAdb(versionOutput: string): WindowsAdbReport | undefined {
205+
const installPath = androidAdbInstallPath(versionOutput);
206+
if (installPath && isWindowsHostPath(installPath)) {
207+
return { detectedVia: 'installed-as-path', adbPath: installPath };
208+
}
209+
if (reportsWindowsRuntime(versionOutput)) {
210+
return { detectedVia: 'running-on-line', adbPath: undefined };
211+
}
212+
return undefined;
213+
}
214+
193215
/**
194-
* A Windows adb.exe reached from a Linux host (WSL interop) answers `adb version`, but it resolves
195-
* every host path it is handed as a Windows path, so pulls, pushes, and installs miss the Linux files.
216+
* A Windows adb.exe reached from a POSIX host (WSL interop, Wine, a mounted volume) answers
217+
* `adb version`, but it resolves every host path it is handed as a Windows path, so pulls, pushes,
218+
* and installs miss the host's files. Older and third-party adb builds omit the `Installed as`
219+
* banner, so the `Running on Windows` line is the fallback signal for them.
196220
*/
197221
function windowsAdbOnPosixHostCheck(
198-
probe: Readonly<{ adbPath: string; sdkRoot: string | undefined; versionLine: string }>,
222+
probe: Readonly<{
223+
windowsAdb: WindowsAdbReport;
224+
sdkRoot: string | undefined;
225+
versionLine: string;
226+
}>,
199227
): DoctorCheck {
228+
const { adbPath, detectedVia } = probe.windowsAdb;
200229
return {
201230
id: 'toolchain',
202231
status: 'fail',
203-
summary: `Android toolchain: adb on PATH is the Windows binary ${probe.adbPath}, which cannot use this host's file paths.`,
204-
hint: 'Under WSL, install Linux Android platform-tools, put them first on PATH, and point ANDROID_HOME at a Linux SDK instead of one under /mnt/<drive>.',
232+
summary: `Android toolchain: adb on PATH${adbPath ? ` (${adbPath})` : ''} is a Windows binary, which cannot use this host's file paths.`,
233+
hint: "adb must be a native binary for this host: install this host's Android platform-tools, put them first on PATH, and point ANDROID_HOME at an SDK on this host's filesystem. Under WSL that means a Linux SDK, not one under /mnt/<drive>.",
205234
evidence: {
206235
reason: WINDOWS_ADB_ON_POSIX_HOST_REASON,
207-
adbPath: probe.adbPath,
236+
detectedVia,
237+
adbPath: adbPath ?? null,
208238
adbVersion: probe.versionLine,
209239
androidHome: probe.sdkRoot ?? null,
210240
},

‎website/docs/docs/known-limitations.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ An unattended first Android snapshot therefore times out with a helper install f
4646

4747
## Android: WSL needs Linux platform-tools
4848

49-
Under WSL, the Windows `adb.exe` (for example from an `ANDROID_HOME` under `/mnt/c`) answers `adb version` but resolves every host path it is given as a Windows path, so recordings, pulls, and installs fail. Install Linux Android platform-tools inside WSL, put them first on `PATH`, and point `ANDROID_HOME` at a Linux SDK. `agent-device doctor` fails the toolchain check with reason `android_adb_windows_binary_on_posix_host` when `adb` reports a Windows install path.
49+
Under WSL, the Windows `adb.exe` (for example from an `ANDROID_HOME` under `/mnt/c`) answers `adb version` but resolves every host path it is given as a Windows path, so recordings, pulls, and installs fail. Install Linux Android platform-tools inside WSL, put them first on `PATH`, and point `ANDROID_HOME` at a Linux SDK. `agent-device doctor` fails the toolchain check with reason `android_adb_windows_binary_on_posix_host` when `adb` reports a Windows install path or reports that it is running on Windows. The same check catches a Windows `adb.exe` reached from macOS or Linux through Wine or a mounted volume.
5050

5151
## Android: no clipboard access over adb on Android 16
5252

0 commit comments

Comments
 (0)