solana-mobile 0.0.1 → 0.1.0

package/dist/cli.mjs

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import { Command, InvalidArgumentError } from "commander";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { cancel, intro, isCancel, log, multiselect, note, outro, select, text } from "@clack/prompts";
 import { createApp, detectInvokedPackageManager, fetchTemplateData, finalNote, getAppInfo, listTemplateIds, listTemplates, listVersions, validateProjectName } from "create-solana-dapp";
 import { execFile, spawn } from "node:child_process";
-import { promisify } from "node:util";
-import { homedir } from "node:os";
+import { access, mkdir, readFile, readdir, realpath, statfs, writeFile } from "node:fs/promises";
+import { homedir, platform, release } from "node:os";
 import { constants } from "node:fs";
-import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 //#region package.json
 var package_default = {
 	bin: { "solana-mobile": "dist/cli.mjs" },
@@ -53,7 +52,7 @@ var package_default = {
 		"version": "changeset version && bun lint:fix"
 	},
 	type: "module",
-	version: "0.0.1"
+	version: "0.1.0"
 };
 //#endregion
 //#region src/core/util/read-package-string.ts
@@ -201,97 +200,106 @@ function resolveTemplate(templateName, templates) {
 	};
 }
 //#endregion
+//#region src/doctor/data-access/doctor-environment.ts
+const defaultDoctorEnvironment = {
+	architecture: process.arch,
+	environment: process.env,
+	getDiskSpace: async (path) => {
+		const stats = await statfs(path);
+		return stats.bavail * stats.bsize;
+	},
+	getHomeDirectory: homedir,
+	getPlatform: platform,
+	getRelease: release,
+	listDirectory: async (path) => readdir(path),
+	pathExists: async (path) => access(path).then(() => true, () => false),
+	resolvePath: async (path) => realpath(path),
+	runCommand: runExecutable$1
+};
+function runExecutable$1(command, args = [], timeout = 5e3) {
+	return new Promise((resolvePromise, reject) => {
+		execFile(command, args, {
+			timeout,
+			windowsHide: true
+		}, (error, stdout, stderr) => {
+			if (error) {
+				reject(error);
+				return;
+			}
+			resolvePromise({
+				path: command,
+				stderr,
+				stdout
+			});
+		}).stdin?.end();
+	});
+}
+async function findExecutable(name, environment, preferredDirectories = []) {
+	const extensions = environment.getPlatform() === "win32" ? [
+		"",
+		".exe",
+		".bat",
+		".cmd"
+	] : [""];
+	const pathDirectories = (environment.environment.PATH ?? "").split(delimiter).filter(Boolean);
+	for (const directory of [...preferredDirectories, ...pathDirectories]) for (const extension of extensions) {
+		const candidate = join(directory, `${name}${extension}`);
+		if (await environment.pathExists(candidate)) return candidate;
+	}
+}
+function parseVersion(output) {
+	return output.match(/(?:^|[^\d])(\d+(?:\.\d+){0,3})(?:[^\d]|$)/m)?.[1];
+}
+function sortVersions(values) {
+	return [...values].sort((left, right) => compareVersions(left, right));
+}
+function compareVersions(left, right) {
+	const leftParts = left.split(".").map(Number);
+	const rightParts = right.split(".").map(Number);
+	for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+		const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+//#endregion
 //#region src/doctor/data-access/check-adb-version.ts
-const execFileAsync = promisify(execFile);
 const minimumAdbMajorVersion = 33;
-async function checkAdbVersion(runCommand = runExecutable$1) {
+async function checkAdbVersion(environment = defaultDoctorEnvironment, sdkRoot) {
+	const executable = await findExecutable("adb", environment, sdkRoot ? [join(sdkRoot, "platform-tools")] : []);
+	if (!executable) return missingAdb();
 	try {
-		const version = parseAdbVersion(await runCommand("adb", ["version"]));
-		const majorVersion = version ? Number.parseInt(version, 10) : NaN;
-		if (!version || Number.isNaN(majorVersion)) return {
-			actual: "unknown",
-			message: "Unable to detect adb platform-tools version.",
-			name: "adb",
-			ok: false,
-			recommendation: "Install Android SDK Platform Tools 33 or higher.",
-			required: "33 or higher"
-		};
+		const output = await environment.runCommand(executable, ["version"]);
+		const version = parseAdbVersion(`${output.stdout}\n${output.stderr}`);
+		const passes = Boolean(version) && Number.parseInt(version ?? "", 10) >= minimumAdbMajorVersion;
 		return {
-			actual: version,
-			message: `Detected adb ${version}.`,
+			actual: version ?? "unknown",
+			category: "android-sdk",
+			details: [`Executable: ${executable}`],
+			message: version ? `Detected adb ${version}.` : "Unable to detect adb platform-tools version.",
 			name: "adb",
-			ok: majorVersion >= minimumAdbMajorVersion,
-			recommendation: majorVersion >= minimumAdbMajorVersion ? void 0 : "Update Android SDK Platform Tools to version 33 or higher.",
-			required: "33 or higher"
+			recommendation: passes ? void 0 : "Install or update Android SDK Platform Tools to version 33 or higher.",
+			required: "33 or higher",
+			status: passes ? "pass" : "fail"
 		};
 	} catch {
-		return {
-			actual: "not found",
-			message: "adb is not available on PATH.",
-			name: "adb",
-			ok: false,
-			recommendation: "Install Android SDK Platform Tools 33 or higher and make sure adb is on PATH.",
-			required: "33 or higher"
-		};
+		return missingAdb();
 	}
 }
 function parseAdbVersion(output) {
 	return output.match(/^Version\s+(\d+(?:\.\d+)*)/im)?.[1];
 }
-async function runExecutable$1(command, args) {
-	const { stdout } = await execFileAsync(command, args);
-	return stdout;
-}
-//#endregion
-//#region src/doctor/data-access/check-node-version.ts
-const minimumNodeMajorVersion = 22;
-function checkNodeVersion(version = process.version) {
-	const normalizedVersion = normalizeNodeVersion(version);
-	const majorVersion = normalizedVersion ? Number.parseInt(normalizedVersion, 10) : NaN;
-	if (!normalizedVersion || Number.isNaN(majorVersion)) return {
-		actual: "unknown",
-		message: "Unable to detect Node.js version.",
-		name: "node",
-		ok: false,
-		recommendation: "Install Node.js 22 or higher.",
-		required: "22 or higher"
-	};
+function missingAdb() {
 	return {
-		actual: normalizedVersion,
-		message: `Detected Node.js ${normalizedVersion}.`,
-		name: "node",
-		ok: majorVersion >= minimumNodeMajorVersion,
-		recommendation: majorVersion >= minimumNodeMajorVersion ? void 0 : "Install Node.js 22 or higher.",
-		required: "22 or higher"
+		actual: "not found",
+		category: "android-sdk",
+		message: "adb is not available.",
+		name: "adb",
+		recommendation: "Install Android SDK Platform Tools 33 or higher.",
+		required: "33 or higher",
+		status: "fail"
 	};
 }
-function normalizeNodeVersion(version) {
-	return version.trim().replace(/^v/i, "");
-}
-//#endregion
-//#region src/doctor/ui/doctor-ui-report.ts
-function renderDoctorReport(results) {
-	for (const result of results) {
-		const message = `${result.name}: ${result.actual} (requires ${result.required})`;
-		if (result.ok) log.success(message);
-		else log.error(message);
-	}
-	const recommendations = results.filter((result) => !result.ok && result.recommendation).map((result) => result.recommendation);
-	if (recommendations.length === 0) {
-		outro("Your system is ready.");
-		return;
-	}
-	log.warn("Recommendations");
-	for (const recommendation of recommendations) log.message(`- ${recommendation}`);
-	outro("Run doctor again after applying the recommendations.");
-}
-//#endregion
-//#region src/doctor/doctor-feature-index.ts
-async function runDoctor() {
-	const results = [await checkAdbVersion(), checkNodeVersion()];
-	renderDoctorReport(results);
-	return results.every((result) => result.ok) ? 0 : 1;
-}
 //#endregion
 //#region src/emulator/data-access/resolve-android-sdk-root.ts
 function resolveAndroidSdkRoot(environment = process.env, homeDirectory = homedir()) {
@@ -404,6 +412,712 @@ function getTagDisplay(tagId) {
 	return tagId.split(/[_-]/).filter(Boolean).map((segment) => `${segment[0]?.toUpperCase()}${segment.slice(1).toLowerCase()}`).join(" ");
 }
 //#endregion
+//#region src/emulator/data-access/list-installed-avds.ts
+async function defaultReadDirectory(directoryPath) {
+	return readdir(directoryPath, { withFileTypes: true });
+}
+async function defaultReadTextFile$1(filePath) {
+	return readFile(filePath, "utf8");
+}
+async function listInstalledAvds({ getHomeDirectory = homedir, readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile$1 } = {}) {
+	const avdRootDirectory = join(getHomeDirectory(), ".android", "avd");
+	const avdEntryNames = await listEntryNames(avdRootDirectory, readDirectory);
+	const registeredAvdNames = new Set(avdEntryNames.filter((name) => name.endsWith(".ini")).map((name) => name.slice(0, -4)));
+	const avdDirectoryNames = avdEntryNames.filter((name) => name.endsWith(".avd") && registeredAvdNames.has(name.slice(0, -4)));
+	return (await Promise.all(avdDirectoryNames.map(async (directoryName) => {
+		const configPath = join(avdRootDirectory, directoryName, "config.ini");
+		const name = directoryName.slice(0, -4);
+		let configValues = {};
+		try {
+			configValues = parseAvdConfig(await readTextFile(configPath));
+		} catch {
+			configValues = {};
+		}
+		return {
+			device: configValues["hw.device.name"],
+			name,
+			target: configValues.target
+		};
+	}))).sort((left, right) => left.name.localeCompare(right.name));
+}
+async function listEntryNames(directoryPath, readDirectory) {
+	try {
+		return (await readDirectory(directoryPath)).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/doctor/data-access/check-android-devices.ts
+function parseAdbDevices(output) {
+	return output.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("List of devices attached")).flatMap((line) => {
+		const [serial, state, ...parts] = line.split(/\s+/);
+		if (!serial || !state) return [];
+		return [{
+			attributes: Object.fromEntries(parts.flatMap((part) => {
+				const index = part.indexOf(":");
+				return index > 0 ? [[part.slice(0, index), part.slice(index + 1)]] : [];
+			})),
+			kind: serial.startsWith("emulator-") ? "emulator" : "physical",
+			serial,
+			state
+		}];
+	}).sort((left, right) => left.serial.localeCompare(right.serial));
+}
+async function checkAndroidDevices(environment, adbAvailable, sdkRoot, installedAvds) {
+	const avdNames = (installedAvds ?? await listInstalledAvds()).map(({ name }) => name);
+	const avdCheck = {
+		actual: avdNames.length ? `${avdNames.length} installed (${avdNames.join(", ")})` : "none installed",
+		category: "emulator",
+		message: avdNames.length ? `Detected ${avdNames.length} installed Android emulator(s).` : "No Android emulators are installed.",
+		name: "Android emulators",
+		recommendation: avdNames.length ? void 0 : "Create one with: npx solana-mobile emulator create",
+		status: avdNames.length ? "pass" : "warn"
+	};
+	if (!adbAvailable) return [
+		avdCheck,
+		{
+			actual: "unknown",
+			category: "emulator",
+			message: "Running emulators cannot be checked without adb.",
+			name: "Running emulators",
+			status: "info"
+		},
+		{
+			actual: "unknown",
+			category: "device",
+			message: "Physical devices cannot be checked without adb.",
+			name: "Physical devices",
+			status: "info"
+		}
+	];
+	const adbExecutable = await findExecutable("adb", environment, sdkRoot ? [join(sdkRoot, "platform-tools")] : []);
+	if (!adbExecutable) return [
+		avdCheck,
+		{
+			actual: "unknown",
+			category: "emulator",
+			message: "Running emulators cannot be checked without adb.",
+			name: "Running emulators",
+			status: "info"
+		},
+		{
+			actual: "unknown",
+			category: "device",
+			message: "Physical devices cannot be checked without adb.",
+			name: "Physical devices",
+			status: "info"
+		}
+	];
+	let devices = [];
+	try {
+		devices = parseAdbDevices((await environment.runCommand(adbExecutable, ["devices", "-l"])).stdout);
+	} catch {}
+	const emulators = devices.filter(({ kind }) => kind === "emulator");
+	const physical = devices.filter(({ kind }) => kind === "physical");
+	const running = {
+		actual: emulators.length ? emulators.map(({ serial, state }) => `${serial} (${state})`).join(", ") : "none",
+		category: "emulator",
+		details: emulators.map(({ serial }) => `Serial: ${serial}`),
+		message: emulators.length ? "Detected running emulator instances." : "No emulator is currently running.",
+		name: "Running emulators",
+		status: "info"
+	};
+	const authorized = physical.filter(({ state }) => state === "device");
+	const problematic = physical.filter(({ state }) => state !== "device");
+	const recommendation = problematic.some(({ state }) => state === "unauthorized") ? "Unlock the phone and accept the USB debugging authorization dialog." : problematic.length ? "Reconnect the offline Android device and restart adb if necessary." : void 0;
+	return [
+		avdCheck,
+		running,
+		{
+			actual: physical.length ? physical.map(formatPhysicalDevice).join(", ") : "none connected",
+			category: "device",
+			details: physical.map(({ serial }) => `Serial: ${serial}`),
+			message: authorized.length ? `Detected ${authorized.length} authorized physical device(s).` : problematic.length ? "A physical device is connected but unavailable." : "No physical Android device is connected.",
+			name: "Physical devices",
+			recommendation,
+			status: authorized.length ? "pass" : problematic.length ? "warn" : "info"
+		}
+	];
+}
+async function checkEmulatorAcceleration(environment) {
+	const platform = environment.getPlatform();
+	if (platform === "darwin") return {
+		actual: "Hypervisor Framework available on supported Macs",
+		category: "emulator",
+		message: "macOS Android Emulator uses Hypervisor Framework when supported.",
+		name: "Emulator acceleration",
+		status: "info"
+	};
+	if (platform === "linux") {
+		const available = await access("/dev/kvm").then(() => true, () => false);
+		return {
+			actual: available ? "/dev/kvm available" : "/dev/kvm unavailable",
+			category: "emulator",
+			message: available ? "KVM acceleration is available." : "KVM acceleration is unavailable or inaccessible.",
+			name: "Emulator acceleration",
+			recommendation: available ? void 0 : "Enable KVM and grant the current user access to /dev/kvm.",
+			status: available ? "pass" : "warn"
+		};
+	}
+	return {
+		actual: "unknown",
+		category: "emulator",
+		message: "Emulator acceleration could not be determined reliably.",
+		name: "Emulator acceleration",
+		status: "info"
+	};
+}
+function formatPhysicalDevice(device) {
+	return `${device.attributes.model?.replaceAll("_", " ") ?? device.serial} (${device.state === "device" ? "authorized" : device.state})`;
+}
+//#endregion
+//#region src/doctor/data-access/check-android-sdk.ts
+async function resolveAndroidSdk(environment) {
+	const home = environment.getHomeDirectory();
+	const defaults = {
+		darwin: join(home, "Library", "Android", "sdk"),
+		linux: join(home, "Android", "Sdk"),
+		win32: environment.environment.LOCALAPPDATA ? join(environment.environment.LOCALAPPDATA, "Android", "Sdk") : void 0
+	};
+	const candidates = [
+		{
+			path: environment.environment.ANDROID_HOME,
+			source: "ANDROID_HOME"
+		},
+		{
+			path: environment.environment.ANDROID_SDK_ROOT,
+			source: "ANDROID_SDK_ROOT"
+		},
+		{
+			path: defaults[environment.getPlatform()],
+			source: "default location"
+		}
+	].filter((value) => Boolean(value.path));
+	const homeValue = environment.environment.ANDROID_HOME;
+	const rootValue = environment.environment.ANDROID_SDK_ROOT;
+	const conflict = homeValue && rootValue && homeValue !== rootValue ? `${homeValue} conflicts with ${rootValue}` : void 0;
+	for (const candidate of candidates) if (await environment.pathExists(candidate.path)) return {
+		conflict,
+		path: await environment.resolvePath(candidate.path).catch(() => candidate.path),
+		searched: candidates.map(({ path }) => path),
+		source: candidate.source
+	};
+	return {
+		conflict,
+		searched: candidates.map(({ path }) => path)
+	};
+}
+async function checkAndroidSdk(environment, resolution) {
+	const checks = [];
+	checks.push({
+		actual: resolution.path ? `${resolution.path} (${resolution.source})` : "not found",
+		category: "android-sdk",
+		details: [`Searched: ${resolution.searched.join(", ") || "no locations available"}`],
+		message: resolution.path ? `Resolved Android SDK from ${resolution.source}.` : "No valid Android SDK directory was found.",
+		name: "Android SDK",
+		recommendation: resolution.path ? void 0 : "Install the Android SDK or set ANDROID_HOME to its location.",
+		status: resolution.path ? "pass" : "fail"
+	});
+	if (resolution.conflict) checks.push({
+		actual: resolution.conflict,
+		category: "android-sdk",
+		message: "ANDROID_HOME and ANDROID_SDK_ROOT point to different locations.",
+		name: "Android SDK environment",
+		recommendation: "Make ANDROID_HOME and ANDROID_SDK_ROOT point to the same Android SDK.",
+		status: "warn"
+	});
+	if (!resolution.path) return checks;
+	checks.push(await checkVersionDirectories(environment, resolution.path, "platforms", "Android platforms", "android-", "Install an Android SDK platform through Android Studio SDK Manager."));
+	checks.push(await checkVersionDirectories(environment, resolution.path, "build-tools", "Build Tools", "", "Install Android SDK Build Tools through Android Studio SDK Manager."));
+	checks.push(await checkTool(environment, resolution.path, "emulator", [join(resolution.path, "emulator")], "Emulator", "Install Android Emulator through Android Studio SDK Manager.", "warn"));
+	const commandLineDirectories = await commandLineToolDirectories(environment, resolution.path);
+	checks.push(await checkTool(environment, resolution.path, "avdmanager", commandLineDirectories, "avdmanager", "Install Android SDK Command-line Tools; avdmanager is needed by solana-mobile emulator create.", "warn"));
+	const sdkManagerExecutable = await findExecutable("sdkmanager", environment, commandLineDirectories);
+	const sdkManager = await checkTool(environment, resolution.path, "sdkmanager", commandLineDirectories, "sdkmanager", "Install Android SDK Command-line Tools through Android Studio SDK Manager.", "warn", sdkManagerExecutable);
+	checks.push(sdkManager);
+	checks.push(await checkSdkLicenses(environment, sdkManagerExecutable));
+	return checks;
+}
+async function checkSdkLicenses(environment, sdkManagerExecutable) {
+	const instruction = `Run: ${sdkManagerExecutable ?? "sdkmanager"} --licenses`;
+	if (!sdkManagerExecutable) return {
+		actual: "unable to check",
+		category: "android-sdk",
+		message: "SDK licenses cannot be checked because sdkmanager is unavailable.",
+		name: "SDK licenses",
+		recommendation: instruction,
+		status: "info"
+	};
+	try {
+		const output = await environment.runCommand(sdkManagerExecutable, ["--licenses"]);
+		const status = parseSdkLicenseStatus(`${output.stdout}\n${output.stderr}`);
+		if (status === "accepted") return {
+			actual: "all accepted",
+			category: "android-sdk",
+			message: "All Android SDK package licenses are accepted.",
+			name: "SDK licenses",
+			status: "pass"
+		};
+		return {
+			actual: status === "unaccepted" ? "acceptance required" : "unable to verify",
+			category: "android-sdk",
+			message: "Android SDK package licenses require attention.",
+			name: "SDK licenses",
+			recommendation: instruction,
+			status: status === "unaccepted" ? "warn" : "info"
+		};
+	} catch {
+		return {
+			actual: "unable to verify",
+			category: "android-sdk",
+			message: "Android SDK package license status could not be determined.",
+			name: "SDK licenses",
+			recommendation: instruction,
+			status: "info"
+		};
+	}
+}
+function parseSdkLicenseStatus(output) {
+	if (/all sdk package licenses accepted/i.test(output)) return "accepted";
+	if (/licenses?.*not been accepted|accept\?\s*\(y\/n\)/is.test(output)) return "unaccepted";
+	return "unknown";
+}
+async function checkVersionDirectories(environment, sdkRoot, directory, name, prefix, recommendation) {
+	const versions = sortVersions((await environment.listDirectory(join(sdkRoot, directory)).catch(() => [])).map((entry) => entry.startsWith(prefix) ? entry.slice(prefix.length) : entry).filter((entry) => /^\d+(?:\.\d+)*$/.test(entry)));
+	return {
+		actual: versions.length ? name === "Android platforms" ? versions.map((version) => `API ${version}`).join(", ") : versions.at(-1) ?? "" : "none installed",
+		category: "android-sdk",
+		details: versions.map((version) => `${name}: ${version}`),
+		message: versions.length ? `Detected ${versions.length} installed ${name.toLowerCase()} version(s).` : `No ${name} are installed.`,
+		name,
+		recommendation: versions.length ? void 0 : recommendation,
+		required: "at least one installed version",
+		status: versions.length ? "pass" : "fail"
+	};
+}
+async function commandLineToolDirectories(environment, sdkRoot) {
+	const root = join(sdkRoot, "cmdline-tools");
+	return (await environment.listDirectory(root).catch(() => [])).sort().map((entry) => join(root, entry, "bin"));
+}
+async function checkTool(environment, sdkRoot, command, directories, name, recommendation, missingStatus, resolvedExecutable) {
+	const executable = resolvedExecutable ?? await findExecutable(command, environment, directories);
+	if (!executable) return {
+		actual: "not found",
+		category: name === "Emulator" ? "emulator" : "android-sdk",
+		message: `${name} is not available.`,
+		name,
+		recommendation,
+		status: missingStatus
+	};
+	let version;
+	try {
+		const output = await environment.runCommand(executable, ["-version"]);
+		version = parseVersion(`${output.stdout}\n${output.stderr}`);
+	} catch {
+		version = void 0;
+	}
+	return {
+		actual: version ?? "available",
+		category: name === "Emulator" ? "emulator" : "android-sdk",
+		details: [`Executable: ${executable}`, `SDK root: ${sdkRoot}`],
+		message: `${name} is available.`,
+		name,
+		status: "pass"
+	};
+}
+//#endregion
+//#region src/doctor/data-access/check-java.ts
+function parseJavaVersion(output) {
+	const quoted = output.match(/version\s+"([^"]+)"/i)?.[1];
+	return quoted ? parseVersion(quoted) : parseVersion(output);
+}
+async function checkJava(environment) {
+	const java = await checkJavaExecutable(environment);
+	const compiler = await checkJavaCompiler(environment, java.status !== "fail");
+	return [
+		java,
+		compiler,
+		await checkJavaHome(environment, java.status !== "fail" && compiler.status !== "fail")
+	];
+}
+async function checkJavaExecutable(environment) {
+	const executable = await findExecutable("java", environment);
+	if (!executable) return javaFailure("Java", "Java is not available.", "Install JDK 17 or higher.");
+	try {
+		const result = await environment.runCommand(executable, ["-version"]);
+		const version = parseJavaVersion(`${result.stdout}\n${result.stderr}`);
+		const passes = Boolean(version) && Number.parseInt(version ?? "", 10) >= 17;
+		return {
+			actual: version ?? "unknown",
+			category: "java",
+			details: [`Executable: ${executable}`],
+			message: version ? `Detected Java ${version}.` : "Unable to parse the Java version.",
+			name: "Java",
+			recommendation: passes ? void 0 : "Install JDK 17 or higher.",
+			required: "17 or higher",
+			status: passes ? "pass" : "fail"
+		};
+	} catch {
+		return javaFailure("Java", "Java is not usable.", "Install JDK 17 or higher.");
+	}
+}
+async function checkJavaCompiler(environment, javaAvailable) {
+	const executable = await findExecutable("javac", environment);
+	if (!executable) return javaFailure("Java compiler", "javac is not available.", "Install a complete JDK 17 or higher, not only a JRE.");
+	try {
+		const result = await environment.runCommand(executable, ["-version"]);
+		const version = parseJavaVersion(`${result.stdout}\n${result.stderr}`);
+		return {
+			actual: version ?? "available",
+			category: "java",
+			details: [`Executable: ${executable}`],
+			message: `Detected Java compiler ${version ?? ""}.`.trim(),
+			name: "Java compiler",
+			required: "JDK 17 or higher",
+			status: javaAvailable ? "pass" : "fail"
+		};
+	} catch {
+		return javaFailure("Java compiler", "javac is not usable.", "Install a complete JDK 17 or higher.");
+	}
+}
+async function checkJavaHome(environment, toolsAvailable) {
+	const configured = environment.environment.JAVA_HOME;
+	if (!configured) return {
+		actual: "not set",
+		category: "java",
+		message: "JAVA_HOME is not set.",
+		name: "JAVA_HOME",
+		recommendation: "Set JAVA_HOME to your JDK path to make Java discovery deterministic.",
+		status: toolsAvailable ? "warn" : "fail"
+	};
+	const resolved = await environment.resolvePath(configured).catch(() => configured);
+	const javaPath = join(resolved, "bin", environment.getPlatform() === "win32" ? "java.exe" : "java");
+	if (!await environment.pathExists(resolved) || !await environment.pathExists(javaPath)) return {
+		actual: resolved,
+		category: "java",
+		message: "JAVA_HOME does not point to a usable JDK.",
+		name: "JAVA_HOME",
+		recommendation: environment.getPlatform() === "win32" ? "Set JAVA_HOME to the installed JDK directory in Windows environment variables." : "Set JAVA_HOME to the installed JDK directory.",
+		status: "fail"
+	};
+	return {
+		actual: resolved,
+		category: "java",
+		details: [`Java executable: ${javaPath}`],
+		message: `JAVA_HOME resolves to ${resolved}.`,
+		name: "JAVA_HOME",
+		status: "pass"
+	};
+}
+function javaFailure(name, message, recommendation) {
+	return {
+		actual: "not found",
+		category: "java",
+		message,
+		name,
+		recommendation,
+		required: "17 or higher",
+		status: "fail"
+	};
+}
+function checkNodeVersion(version = process.version) {
+	const normalizedVersion = normalizeNodeVersion(version);
+	const majorVersion = Number.parseInt(normalizedVersion, 10);
+	const passes = Boolean(normalizedVersion) && !Number.isNaN(majorVersion) && majorVersion >= 22;
+	return {
+		actual: normalizedVersion || "unknown",
+		category: "javascript",
+		message: passes ? `Detected Node.js ${normalizedVersion}.` : "Node.js 22 or higher is required.",
+		name: "Node.js",
+		recommendation: passes ? void 0 : "Install Node.js 22 or higher.",
+		required: "22 or higher",
+		status: passes ? "pass" : "fail"
+	};
+}
+function normalizeNodeVersion(version) {
+	return version.trim().replace(/^v/i, "");
+}
+//#endregion
+//#region src/doctor/data-access/check-system-and-javascript.ts
+const gigabyte = 1024 ** 3;
+function checkOperatingSystem(environment) {
+	const names = {
+		darwin: "macOS",
+		linux: "Linux",
+		win32: "Windows"
+	};
+	const platform = environment.getPlatform();
+	const actual = `${names[platform] ?? "Unknown platform"} ${environment.getRelease()} ${environment.architecture}`;
+	return {
+		actual,
+		category: "system",
+		message: `Detected ${actual}.`,
+		name: "Operating system",
+		status: names[platform] ? "pass" : "info"
+	};
+}
+async function checkDiskSpace(environment, path = process.cwd()) {
+	try {
+		const available = await environment.getDiskSpace(path) / gigabyte;
+		const status = available < 10 ? "fail" : available < 20 ? "warn" : "pass";
+		return {
+			actual: `${Math.floor(available)} GB available`,
+			category: "system",
+			message: `Detected ${Math.floor(available)} GB of available disk space.`,
+			name: "Disk space",
+			recommendation: status === "pass" ? void 0 : "Free disk space for Android SDK packages, emulator images, Gradle caches, and project dependencies.",
+			required: "10 GB minimum; 20 GB recommended",
+			status
+		};
+	} catch {
+		return {
+			actual: "unknown",
+			category: "system",
+			message: "Unable to determine available disk space.",
+			name: "Disk space",
+			status: "info"
+		};
+	}
+}
+const packageManagers = [
+	{
+		command: "bun",
+		label: "Bun"
+	},
+	{
+		command: "npm",
+		label: "npm"
+	},
+	{
+		command: "pnpm",
+		label: "pnpm"
+	},
+	{
+		command: "yarn",
+		label: "Yarn"
+	}
+];
+async function checkPackageManagers(environment) {
+	const found = (await Promise.all(packageManagers.map(async ({ command, label }) => {
+		const executable = await findExecutable(command, environment);
+		if (!executable) return void 0;
+		try {
+			const result = await environment.runCommand(executable, ["--version"]);
+			return {
+				detail: `${label}: ${executable}`,
+				value: `${label} ${parseVersion(result.stdout) ?? "unknown"}`
+			};
+		} catch {
+			return;
+		}
+	}))).filter((value) => Boolean(value));
+	return {
+		actual: found.length ? found.map(({ value }) => value).join(", ") : "none found",
+		category: "javascript",
+		details: found.map(({ detail }) => detail),
+		message: found.length ? `Detected ${found.length} supported package manager(s).` : "No supported package manager found.",
+		name: "Package managers",
+		recommendation: found.length ? void 0 : "Install npm, pnpm, Yarn, or Bun.",
+		required: "at least one of npm, pnpm, Yarn, or Bun",
+		status: found.length ? "pass" : "fail"
+	};
+}
+//#endregion
+//#region src/doctor/ui/doctor-ui-report.ts
+const sections = [
+	{
+		categories: ["system"],
+		checks: ["Operating system", "Disk space"],
+		title: "System"
+	},
+	{
+		categories: ["javascript"],
+		checks: ["Node.js", "Package managers"],
+		title: "JavaScript"
+	},
+	{
+		categories: ["java"],
+		checks: [
+			"Java",
+			"Java compiler",
+			"JAVA_HOME"
+		],
+		title: "Java"
+	},
+	{
+		categories: ["android-sdk"],
+		checks: [
+			"Android SDK",
+			"Android SDK environment",
+			"Android platforms",
+			"Build Tools",
+			"adb",
+			"sdkmanager",
+			"avdmanager",
+			"SDK licenses"
+		],
+		title: "Android SDK"
+	},
+	{
+		categories: ["emulator", "device"],
+		checks: [
+			"Emulator",
+			"Android emulators",
+			"Running emulators",
+			"Emulator acceleration",
+			"Physical devices"
+		],
+		title: "Devices"
+	}
+];
+const styles = {
+	fail: ["\x1B[31m", "\x1B[39m"],
+	heading: ["\x1B[1m", "\x1B[22m"],
+	info: ["\x1B[36m", "\x1B[39m"],
+	muted: ["\x1B[2m", "\x1B[22m"],
+	pass: ["\x1B[32m", "\x1B[39m"],
+	warn: ["\x1B[33m", "\x1B[39m"]
+};
+const symbols = {
+	fail: "✗",
+	info: "•",
+	pass: "✓",
+	warn: "!"
+};
+function renderDoctorReport(report, verbose = false) {
+	process.stdout.write(`${formatDoctorReport(report, verbose, Boolean(process.stdout.isTTY))}\n`);
+}
+function formatDoctorReport(report, verbose = false, color = false) {
+	const output = [paint("Solana Mobile Doctor", "heading", color)];
+	for (const section of sections) {
+		const checks = report.checks.filter(({ category }) => section.categories.includes(category)).sort((left, right) => checkOrder(section.checks, left.name) - checkOrder(section.checks, right.name));
+		if (!checks.length) continue;
+		output.push("", paint(section.title, "heading", color), ...formatChecks(checks, verbose, color));
+	}
+	const readiness = [
+		capability("Project creation", report.capabilities.projectCreation),
+		capability("Android build", report.capabilities.androidBuild),
+		capability("Emulator workflow", report.capabilities.emulator),
+		capability("Physical device workflow", report.capabilities.physicalDevice)
+	];
+	output.push("", paint("Readiness", "heading", color), ...formatChecks(readiness, false, color));
+	if (report.recommendations.length) {
+		output.push("", paint("Recommendations", "heading", color));
+		for (const { name, recommendation } of recommendationChecks(report)) output.push(`  ${paint("!", "warn", color)} ${name}: ${recommendation}`);
+	}
+	const summaryStatus = report.ready ? "pass" : report.capabilities.projectCreation ? "warn" : "fail";
+	output.push("", `${paint(symbols[summaryStatus], summaryStatus, color)} ${finalMessage(report)}`);
+	return output.join("\n");
+}
+function capability(name, ready) {
+	return {
+		actual: ready ? "ready" : "unavailable",
+		category: "system",
+		message: "",
+		name,
+		status: ready ? "pass" : "info"
+	};
+}
+function checkOrder(order, name) {
+	const index = order.indexOf(name);
+	return index === -1 ? order.length : index;
+}
+function finalMessage(report) {
+	if (report.capabilities.projectCreation && report.capabilities.androidBuild) return "Ready for Solana Mobile development.";
+	if (report.capabilities.projectCreation) return "Project creation is ready; the Android environment needs attention.";
+	return "Not ready for Solana Mobile development.";
+}
+function formatChecks(checks, verbose, color) {
+	const labelWidth = Math.max(...checks.map(({ name }) => name.length));
+	return checks.flatMap((check) => {
+		const requirement = check.status === "pass" || !check.required ? "" : ` (requires ${check.required})`;
+		const line = `  ${paint(symbols[check.status], check.status, color)} ${check.name.padEnd(labelWidth)}  ${check.actual}${requirement}`;
+		if (!verbose || !check.details?.length) return [line];
+		return [line, ...check.details.map((detail) => `    ${" ".repeat(labelWidth)}  ${paint(detail, "muted", color)}`)];
+	});
+}
+function paint(value, style, color) {
+	if (!color) return value;
+	const [open, close] = styles[style];
+	return `${open}${value}${close}`;
+}
+function recommendationChecks(report) {
+	const seen = /* @__PURE__ */ new Set();
+	return report.checks.filter(({ recommendation }) => {
+		if (!recommendation || seen.has(recommendation)) return false;
+		seen.add(recommendation);
+		return true;
+	});
+}
+//#endregion
+//#region src/doctor/doctor-feature-index.ts
+async function createDoctorReport(environment = defaultDoctorEnvironment) {
+	const [disk, packageManagers, java] = await Promise.all([
+		checkDiskSpace(environment),
+		checkPackageManagers(environment),
+		checkJava(environment)
+	]);
+	const sdkResolution = await resolveAndroidSdk(environment);
+	const [sdkChecks, adb, acceleration] = await Promise.all([
+		checkAndroidSdk(environment, sdkResolution),
+		checkAdbVersion(environment, sdkResolution.path),
+		checkEmulatorAcceleration(environment)
+	]);
+	const deviceChecks = await checkAndroidDevices(environment, adb.status === "pass", sdkResolution.path);
+	return buildDoctorReport([
+		checkOperatingSystem(environment),
+		disk,
+		checkNodeVersion(),
+		packageManagers,
+		...java,
+		...sdkChecks,
+		adb,
+		acceleration,
+		...deviceChecks
+	]);
+}
+function buildDoctorReport(checks) {
+	const capabilities = deriveCapabilities(checks);
+	return {
+		capabilities,
+		checks,
+		ready: capabilities.projectCreation && capabilities.androidBuild,
+		recommendations: [...new Set(checks.flatMap(({ recommendation }) => recommendation ? [recommendation] : []))]
+	};
+}
+function deriveCapabilities(checks) {
+	const passes = (name) => checks.some((check) => check.name === name && check.status === "pass");
+	const androidBuild = [
+		"Android SDK",
+		"Android platforms",
+		"Build Tools",
+		"Java",
+		"Java compiler",
+		"adb"
+	].every(passes);
+	const projectCreation = ["Node.js", "Package managers"].every(passes);
+	return {
+		androidBuild,
+		emulator: androidBuild && [
+			"Android emulators",
+			"Emulator",
+			"avdmanager"
+		].every(passes),
+		physicalDevice: androidBuild && passes("Physical devices"),
+		projectCreation
+	};
+}
+async function runDoctor(options = {}) {
+	const report = await createDoctorReport();
+	if (options.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+	else renderDoctorReport(report, options.verbose);
+	return getDoctorExitCode(report);
+}
+function getDoctorExitCode(report) {
+	return report.checks.some(({ status }) => status === "fail") ? 1 : 0;
+}
+//#endregion
 //#region src/emulator/data-access/run-executable.ts
 async function runExecutable(cmd, options = {}) {
 	return new Promise((resolve, reject) => {
@@ -435,7 +1149,7 @@ async function runExecutable(cmd, options = {}) {
 }
 //#endregion
 //#region src/emulator/data-access/create-avd.ts
-async function createAvd(options, { getHomeDirectory = homedir, pathExists = defaultPathExists(), readTextFile = defaultReadTextFile$1, runCommand = runExecutable, writeTextFile = defaultWriteTextFile } = {}) {
+async function createAvd(options, { getHomeDirectory = homedir, pathExists = defaultPathExists(), readTextFile = defaultReadTextFile, runCommand = runExecutable, writeTextFile = defaultWriteTextFile } = {}) {
 	const resolvedOptions = resolveCreateOptions(options);
 	const toolPaths = getToolPaths(resolvedOptions.sdkRoot);
 	const homeDirectory = getHomeDirectory();
@@ -504,49 +1218,13 @@ function getAvdConfigPath(homeDirectory, avdName) {
 function getSystemImageDirectory(sdkRoot, systemImage) {
 	return join(sdkRoot, ...systemImage.split(";"));
 }
-async function defaultReadTextFile$1(filePath) {
+async function defaultReadTextFile(filePath) {
 	return readFile(filePath, "utf8");
 }
 async function isInstalledSystemImage(sdkRoot, systemImage, pathExists) {
 	return pathExists(join(getSystemImageDirectory(sdkRoot, systemImage), "source.properties"));
 }
 //#endregion
-//#region src/emulator/data-access/list-installed-avds.ts
-async function defaultReadDirectory(directoryPath) {
-	return readdir(directoryPath, { withFileTypes: true });
-}
-async function defaultReadTextFile(filePath) {
-	return readFile(filePath, "utf8");
-}
-async function listInstalledAvds({ getHomeDirectory = homedir, readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile } = {}) {
-	const avdRootDirectory = join(getHomeDirectory(), ".android", "avd");
-	const avdEntryNames = await listEntryNames(avdRootDirectory, readDirectory);
-	const registeredAvdNames = new Set(avdEntryNames.filter((name) => name.endsWith(".ini")).map((name) => name.slice(0, -4)));
-	const avdDirectoryNames = avdEntryNames.filter((name) => name.endsWith(".avd") && registeredAvdNames.has(name.slice(0, -4)));
-	return (await Promise.all(avdDirectoryNames.map(async (directoryName) => {
-		const configPath = join(avdRootDirectory, directoryName, "config.ini");
-		const name = directoryName.slice(0, -4);
-		let configValues = {};
-		try {
-			configValues = parseAvdConfig(await readTextFile(configPath));
-		} catch {
-			configValues = {};
-		}
-		return {
-			device: configValues["hw.device.name"],
-			name,
-			target: configValues.target
-		};
-	}))).sort((left, right) => left.name.localeCompare(right.name));
-}
-async function listEntryNames(directoryPath, readDirectory) {
-	try {
-		return (await readDirectory(directoryPath)).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
-	} catch {
-		return [];
-	}
-}
-//#endregion
 //#region src/emulator/data-access/start-emulator.ts
 async function defaultStartProcess(cmd) {
 	await new Promise((resolve, reject) => {
@@ -592,7 +1270,7 @@ async function promptEmulatorName(defaultName = DEFAULT_PROFILE.name, runText =
 }
 //#endregion
 //#region src/emulator/emulator-feature-create.ts
-async function runEmulatorCreate(options = {}, { getHomeDirectory = homedir, pathExists = defaultPathExists(), readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile, runCommand = runExecutable, runText, startProcess = defaultStartProcess, writeTextFile = defaultWriteTextFile } = {}) {
+async function runEmulatorCreate(options = {}, { getHomeDirectory = homedir, pathExists = defaultPathExists(), readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile$1, runCommand = runExecutable, runText, startProcess = defaultStartProcess, writeTextFile = defaultWriteTextFile } = {}) {
 	const profile = resolveEmulatorProfile(options.profile);
 	const name = options.name ?? await promptEmulatorName(profile.name, runText);
 	if (!name) return;
@@ -683,7 +1361,7 @@ async function selectInstalledEmulatorNames(avds, runMultiselect = multiselect)
 }
 //#endregion
 //#region src/emulator/emulator-feature-delete.ts
-async function runEmulatorDelete(options, { getHomeDirectory = homedir, readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile, runCommand = runExecutable, runMultiselect } = {}) {
+async function runEmulatorDelete(options, { getHomeDirectory = homedir, readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile$1, runCommand = runExecutable, runMultiselect } = {}) {
 	const names = options.names && options.names.length > 0 ? options.names : await selectInstalledEmulatorNames(await listInstalledAvds({
 		getHomeDirectory,
 		readDirectory,
@@ -717,7 +1395,7 @@ async function runEmulatorList(_options = {}) {
 }
 //#endregion
 //#region src/emulator/emulator-feature-start.ts
-async function runEmulatorStart(options = {}, { getHomeDirectory = homedir, readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile, runSelect, startProcess = defaultStartProcess } = {}) {
+async function runEmulatorStart(options = {}, { getHomeDirectory = homedir, readDirectory = defaultReadDirectory, readTextFile = defaultReadTextFile$1, runSelect, startProcess = defaultStartProcess } = {}) {
 	const name = options.name ?? await selectInstalledEmulatorName(await listInstalledAvds({
 		getHomeDirectory,
 		readDirectory,
@@ -932,8 +1610,8 @@ function createApp$1({ runEmulatorCreate: runEmulatorCreateCommand = runEmulator
 			template: options.template ?? (options.minimal ? "kit-expo-minimal" : void 0)
 		});
 	});
-	app.command("doctor").description("Check local development dependencies").action(async () => {
-		process.exitCode = await runDoctorCommand();
+	app.command("doctor").description("Check local development dependencies").option("--json", "Print a stable JSON report").option("--verbose", "Include resolved paths and diagnostic details").action(async (options) => {
+		process.exitCode = await runDoctorCommand(options);
 	});
 	const emulatorCommand = app.command("emulator").alias("emu").description("Manage Android emulators");
 	emulatorCommand.action(() => {