fix(sample-app): make it standalone, no repo_root assumptions (#8)

* fix(cli): fall back to node_modules for @uatu/spec resolution

Drop the hard failure when the uatu source tree is not reachable from
the spec file. Users integrating uatu in their own app have @uatu/spec
installed via npm; esbuild now resolves it from node_modules.

* build(gradle): drop :sample-app include from root settings

The sample now has its own Gradle project in examples/sample-app/android.

* build(sample-app): vendor gradle wrapper

Users running the sample build the APK via ./gradlew from inside the
sample-app's own android/ directory, no repo-root wrapper required.

* build(sample-app): make gradle project standalone

Drop the project(':sdk-android') dependency in favor of the Maven
Central coordinate io.github.priyanshujain:sdk-android. The sample now
owns its settings.gradle.kts and gradle.properties, so it builds
without any pieces of the uatu source tree.

* chore(sample-app): declare @uatu/spec npm dependency

Mirrors what a downstream user would put in their own package.json.
Uses file: for pre-release development; becomes a normal semver pin
once @uatu/spec ships to npm.

* docs(sample-app): rewrite justfile and add README

Justfile drops repo_root; all recipes run against the local gradle
wrapper and uatu from PATH. README is scoped to what a user needs to
run the sample against their own device.

* docs(manual): update sample install steps to standalone layout

./gradlew :sample-app:installDebug no longer exists; the sample owns
its own wrapper under android/.

* feat(sdk): log when Uatu.start succeeds

Silent SDK start makes the "SDK didn't connect" failure mode
impossible to debug. One INFO line at start time is enough.

* fix(sidecar): launch via am start -W instead of monkey

monkey -p <pkg> -c LAUNCHER 1 is unreliable on API 36+: it reports no
error but silently fails to start the activity, so the SDK never runs
and the CLI times out on the SDK-accept handshake.

Resolve the launcher activity via `cmd package resolve-activity
--brief` and launch it with `am start -W -n`. -W makes the call block
until the activity is up, which also makes the subsequent SDK
accept timing deterministic.

* feat(cli): auto-resolve Android device; boot AVD if none connected

--avd becomes optional. Resolution order:
 - use any already-connected adb device;
 - else if --avd names an existing AVD, boot it and wait for boot;
 - else if --avd is missing or names no AVD, error with a clear message.

Falls back to $ANDROID_HOME/emulator/emulator when the binary is not on
PATH, so a standard Android SDK install works without extra shell setup.

* docs(sample-app): AVD is optional; document both paths

just test runs against any connected device. If none, pass AVD=<name>
to have uatu boot the emulator for you.

* feat(cli): auto-discover Android SDK; auto-pick the lone AVD

adb and emulator are looked up via PATH, then $ANDROID_HOME,
$ANDROID_SDK_ROOT, ~/Library/Android/sdk, ~/Android/Sdk, and the
Homebrew cask path. The discovered platform-tools directory is
prepended to the sidecar's PATH so its adb subprocess calls work too.

When --avd isn't passed and no device is connected, the CLI picks the
sole local AVD and boots it. Multiple AVDs → error listing them.

* build(make): add `make install` that go-installs uatu onto PATH

Puts `uatu` into $GOBIN (or $GOPATH/bin) so the sample and any local
dev flow can call it without PATH= prefixes.

* docs(sample-app): zero-config just test; dotenv-load for persistence

Drop the expectation that users prefix commands with PATH=, ANDROID_HOME=,
or AVD=. `just test` now works as-is; optional knobs can be pinned in a
.env file alongside the justfile.

* fix(sample-app): auto-detect ANDROID_HOME for Gradle tasks

The Go CLI finds the SDK itself, but AGP still needs ANDROID_HOME to
resolve `sdk.dir`. The justfile now resolves it from env or canonical
install paths before invoking ./gradlew, so `just install` works out
of the box on a standard Android SDK setup.

* gitignore runs directory for sample app

cmd/uatu/test_run.go

@@ -28,9 +28,14 @@ const (
 )
 
 func runTestPipeline(ctx context.Context, options testOptions, stdout io.Writer) error {
-	specApiPath, err := resolveSpecAPIPath(options.spec)
-	if err != nil {
-		return err
+	if options.platform == "android" {
+		if err := ensureDevice(ctx, options.avd, stdout); err != nil {
+			return err
+		}
+	}
+	aliases := map[string]string{}
+	if specApiPath := resolveSpecAPIPath(options.spec); specApiPath != "" {
+		aliases["@uatu/spec"] = specApiPath
 	}
 	bundle, err := bundler.Bundle(bundler.Options{
 		EntryFile: options.spec,
@@ -38,7 +43,7 @@ func runTestPipeline(ctx context.Context, options testOptions, stdout io.Writer)
 			"UATU_TEST_PHONE": os.Getenv("UATU_TEST_PHONE"),
 			"UATU_TEST_OTP":   os.Getenv("UATU_TEST_OTP"),
 		},
-		Aliases: map[string]string{"@uatu/spec": specApiPath},
+		Aliases: aliases,
 	})
 	if err != nil {
 		return fmt.Errorf("bundle spec: %w", err)
@@ -62,6 +67,7 @@ func runTestPipeline(ctx context.Context, options testOptions, stdout io.Writer)
 	)
 	sidecarCommand.Stdout = stdout
 	sidecarCommand.Stderr = stdout
+	sidecarCommand.Env = envWithAndroidPlatformTools(os.Environ())
 	if err := sidecarCommand.Start(); err != nil {
 		return fmt.Errorf("spawn sidecar: %w", err)
 	}
@@ -193,10 +199,11 @@ func runTestPipeline(ctx context.Context, options testOptions, stdout io.Writer)
 	return nil
 }
 
-// resolveSpecAPIPath finds pkg/spec-api/src/index.ts relative to the spec
-// file or the current working directory so the bundler can resolve
-// `@uatu/spec` imports.
-func resolveSpecAPIPath(specPath string) (string, error) {
+// resolveSpecAPIPath returns the path to pkg/spec-api/src/index.ts inside
+// a uatu source checkout, searched upward from the spec file and the cwd.
+// Returns "" when not found, in which case esbuild resolves @uatu/spec via
+// node_modules the way a downstream user's project would.
+func resolveSpecAPIPath(specPath string) string {
 	candidates := []string{}
 	if absoluteSpec, err := filepath.Abs(specPath); err == nil {
 		directory := filepath.Dir(absoluteSpec)
@@ -214,10 +221,10 @@ func resolveSpecAPIPath(specPath string) (string, error) {
 	}
 	for _, candidate := range candidates {
 		if _, err := os.Stat(candidate); err == nil {
-			return candidate, nil
+			return candidate
 		}
 	}
-	return "", fmt.Errorf("could not locate pkg/spec-api/src/index.ts (searched %d paths)", len(candidates))
+	return ""
 }
 
 func pickFreePort() (int, error) {
@@ -230,10 +237,18 @@ func pickFreePort() (int, error) {
 }
 
 func adbReverse(socket string, port int) error {
-	command := exec.Command("adb", "reverse", "localabstract:"+socket, fmt.Sprintf("tcp:%d", port))
+	adb, err := adbBinary()
+	if err != nil {
+		return err
+	}
+	command := exec.Command(adb, "reverse", "localabstract:"+socket, fmt.Sprintf("tcp:%d", port))
 	return command.Run()
 }
 
 func adbReverseRemove(socket string) error {
-	return exec.Command("adb", "reverse", "--remove", "localabstract:"+socket).Run()
+	adb, err := adbBinary()
+	if err != nil {
+		return err
+	}
+	return exec.Command(adb, "reverse", "--remove", "localabstract:"+socket).Run()
 }