androjack-mcp 1.3.0

package/build/tools/navigation3.js

@@ -0,0 +1,331 @@
+// Tool 14: Navigation 3 Guide
+// Navigation 3 went stable November 2025 — complete architectural rethink from Nav2.
+// This tool exists because AI tools hallucinate Nav2 code for new projects even with
+// internet access (documented Atomic Robot case study, January 2026).
+export async function androidNavigation3Guide(topic) {
+    const t = topic.toLowerCase().trim();
+    // ── Overview / default ─────────────────────────────────────────────────────
+    const overview = `
+# Navigation 3 — Official Reference (Stable, November 2025)
+Source: https://developer.android.com/guide/navigation/navigation-3
+
+## ⚠️ CRITICAL FOR AI TOOLS
+Navigation 3 is the current official navigation library as of November 2025.
+Do NOT generate Navigation 2 (NavController/NavHost/NavGraph) for new projects.
+Google's Nav3 migration docs contain explicit "AI Agent:" annotations — this is how
+aware Google is that AI tools hallucinate stale navigation code.
+
+## Why Nav3 Is a Breaking Paradigm Shift (Not Just a Version Bump)
+
+| Concept | Navigation 2 | Navigation 3 |
+|---------|-------------|-------------|
+| Back stack | Internal library state | Plain Kotlin List<NavEntry<*>> |
+| State management | NavController owns it | You own it (observable, testable) |
+| Navigation trigger | NavController.navigate() | Add/remove from your back stack list |
+| Graph definition | NavHost + composable() destinations | NavDisplay + type-safe NavKey |
+| Adaptive layouts | Separate NavigationSuiteScaffold | Built-in via Scenes API |
+| State persistence | rememberSaveable | rememberNavBackStack (custom serialization) |
+| Testing | Hard — internal state | Easy — back stack is a plain list |
+
+## Core Setup
+
+\`\`\`kotlin
+// libs.versions.toml
+[versions]
+navigation3 = "1.0.0"  // Stable November 2025
+
+[libraries]
+navigation3-compose = { group = "androidx.navigation3", name = "navigation3-ui", version.ref = "navigation3" }
+navigation3-runtime = { group = "androidx.navigation3", name = "navigation3-runtime", version.ref = "navigation3" }
+\`\`\`
+
+\`\`\`kotlin
+// build.gradle.kts
+implementation(libs.navigation3.compose)
+implementation(libs.navigation3.runtime)
+\`\`\`
+
+## NavKey — Type-Safe Destination Keys
+
+\`\`\`kotlin
+// Each destination is a serializable key — NOT a route string
+@Serializable
+data object HomeKey  // Simple screen
+
+@Serializable
+data class ProfileKey(val userId: String)  // Screen with args — type-safe, no stringly-typed routes
+
+@Serializable
+data class DetailKey(val itemId: Int, val title: String)
+\`\`\`
+
+## rememberNavBackStack — Your Back Stack
+
+\`\`\`kotlin
+// The back stack is a plain Kotlin list you control
+// NOT NavController.navigate() — you add/remove entries directly
+val backStack = rememberNavBackStack(HomeKey)  // Start with HomeKey
+
+// Navigate forward
+backStack.add(ProfileKey(userId = "abc123"))
+
+// Go back
+backStack.removeLastOrNull()
+
+// Go back to specific destination (like popUpTo)
+backStack.removeAll { it.key is ProfileKey }
+
+// Replace current
+backStack[backStack.lastIndex] = DetailKey(itemId = 1, title = "Item")
+\`\`\`
+
+## NavDisplay — The Renderer
+
+\`\`\`kotlin
+@Composable
+fun AppNavigation() {
+  val backStack = rememberNavBackStack(HomeKey)
+
+  NavDisplay(
+    backStack = backStack,
+    entryProvider = entryProvider {
+      entry<HomeKey> { HomeScreen(onNavigateToProfile = { id -> backStack.add(ProfileKey(id)) }) }
+      entry<ProfileKey> { key -> ProfileScreen(userId = key.userId) }
+      entry<DetailKey> { key -> DetailScreen(itemId = key.itemId, title = key.title) }
+    }
+  )
+}
+\`\`\`
+
+## State Persistence — rememberSerializable (NOT rememberSaveable)
+
+\`\`\`kotlin
+// ❌ WRONG — rememberSaveable does NOT work for NavBackStack
+val backStack = rememberSaveable { mutableStateListOf(HomeKey) }
+
+// ✅ CORRECT — rememberNavBackStack uses rememberSerializable internally
+// All NavKey types MUST be @Serializable
+val backStack = rememberNavBackStack(HomeKey)
+\`\`\`
+
+Source: https://developer.android.com/guide/navigation/navigation-3#state-persistence
+`;
+    // ── Scenes API ─────────────────────────────────────────────────────────────
+    const scenes = `
+# Navigation 3 — Scenes API (Adaptive Multi-Pane)
+Source: https://developer.android.com/guide/navigation/navigation-3/adaptive
+
+## What Scenes Does
+
+The Scenes API replaces the need to combine NavigationSuiteScaffold + separate adaptive
+logic. Nav3 Scenes makes the back stack itself adaptive — the same back stack entries
+automatically render as single-pane on phones or multi-pane on tablets/foldables.
+
+\`\`\`kotlin
+// Additional dependency for Scenes
+implementation("androidx.navigation3:navigation3-adaptive:1.0.0")
+\`\`\`
+
+## List-Detail with Scenes
+
+\`\`\`kotlin
+@Serializable data object InboxKey
+@Serializable data class EmailKey(val emailId: String)
+
+@Composable
+fun AdaptiveMailApp() {
+  val backStack = rememberNavBackStack(InboxKey)
+  val adaptiveInfo = currentWindowAdaptiveInfo()
+
+  NavDisplay(
+    backStack = backStack,
+    // Scenes tells NavDisplay how many entries to show simultaneously
+    sceneStrategy = rememberListDetailSceneStrategy(),
+    entryProvider = entryProvider {
+      entry<InboxKey> {
+        InboxScreen(onEmailClick = { id -> backStack.add(EmailKey(id)) })
+      }
+      entry<EmailKey> { key ->
+        // On phone: full screen. On tablet: side-by-side with Inbox.
+        // Zero conditional logic here — Scenes handles it.
+        EmailDetailScreen(emailId = key.emailId)
+      }
+    }
+  )
+}
+\`\`\`
+
+## Custom Scene Strategy
+
+\`\`\`kotlin
+// Show up to 2 entries side-by-side on Expanded width
+val sceneStrategy = remember {
+  TwoPaneSceneStrategy<Any>(
+    showTwoPanes = { adaptiveInfo ->
+      adaptiveInfo.windowSizeClass.windowWidthSizeClass == WindowWidthSizeClass.EXPANDED
+    }
+  )
+}
+\`\`\`
+
+Source: https://developer.android.com/guide/navigation/navigation-3/adaptive
+`;
+    // ── Migration from Nav2 ────────────────────────────────────────────────────
+    const migration = `
+# Navigation 3 — Migrating from Navigation 2
+Source: https://developer.android.com/guide/navigation/navigation-3/migrate
+
+## AI Agent: Read This Section Carefully
+Google embedded "AI Agent:" annotations in the official Nav3 migration guide specifically
+because AI tools were hallucinating outdated Nav3 code. This tool surfaces the key points.
+
+## API Mapping
+
+| Navigation 2 | Navigation 3 Equivalent |
+|-------------|------------------------|
+| NavController | rememberNavBackStack (your list) |
+| NavHost | NavDisplay |
+| composable("route") { } | entry<MyKey> { } |
+| navController.navigate("route") | backStack.add(MyKey) |
+| navController.popBackStack() | backStack.removeLastOrNull() |
+| navController.navigate("route") { popUpTo("other") } | backStack.removeAll { it.key is OtherKey }; backStack.add(MyKey) |
+| arguments bundle | NavKey constructor params (type-safe) |
+| NavDeepLink | Handled separately, not via NavKey |
+| NavGraph nesting | Just add entries — no graph nesting concept |
+
+## Migration Steps
+
+1. **Replace string routes with @Serializable data class/object NavKeys**
+\`\`\`kotlin
+// Before (Nav2)
+composable("profile/{userId}") { backStackEntry ->
+  val userId = backStackEntry.arguments?.getString("userId")
+  ProfileScreen(userId)
+}
+
+// After (Nav3)
+@Serializable data class ProfileKey(val userId: String)
+entry<ProfileKey> { key -> ProfileScreen(key.userId) }
+\`\`\`
+
+2. **Replace NavController with your back stack**
+\`\`\`kotlin
+// Before
+navController.navigate("profile/abc123")
+
+// After
+backStack.add(ProfileKey(userId = "abc123"))
+\`\`\`
+
+3. **Remove NavHost, replace with NavDisplay**
+\`\`\`kotlin
+// Before
+NavHost(navController, startDestination = "home") { ... }
+
+// After
+NavDisplay(backStack = backStack, entryProvider = entryProvider { ... })
+\`\`\`
+
+4. **Update ViewModel navigation** — pass backStack as a parameter or use a shared state holder
+\`\`\`kotlin
+// ViewModel cannot hold NavBackStack directly (lifecycle reasons)
+// Pass navigation callbacks instead
+@Composable
+fun HomeScreen(onNavigateToProfile: (String) -> Unit) { ... }
+
+// In NavDisplay entry:
+entry<HomeKey> {
+  HomeScreen(onNavigateToProfile = { id -> backStack.add(ProfileKey(id)) })
+}
+\`\`\`
+
+## What Does NOT Change in Nav3
+
+- Bottom navigation / NavigationRail / NavigationDrawer — still use NavigationSuiteScaffold
+  (or use the Scenes API which does it automatically for the content area)
+- Deep links — handled at the Activity level, then push the appropriate NavKey onto the stack
+- ViewModel scoping — still use viewModel() inside entry { } blocks, scoped to that entry
+
+Source: https://developer.android.com/guide/navigation/navigation-3/migrate
+`;
+    // ── Testing ────────────────────────────────────────────────────────────────
+    const testing = `
+# Navigation 3 — Testing
+Source: https://developer.android.com/guide/navigation/navigation-3/testing
+
+## Why Nav3 Testing Is Easier Than Nav2
+
+The back stack is a plain Kotlin list. You don't need a NavController mock.
+You don't need NavHostFragment. You just observe the list.
+
+\`\`\`kotlin
+@Test
+fun navigatingToProfile_addsProfileKeyToBackStack() {
+  // Arrange
+  val backStack = mutableStateListOf<Any>(HomeKey)
+
+  // Act
+  backStack.add(ProfileKey(userId = "user1"))
+
+  // Assert — direct list assertion, no NavController involved
+  assertThat(backStack.last()).isEqualTo(ProfileKey(userId = "user1"))
+  assertThat(backStack.size).isEqualTo(2)
+}
+
+@Test
+fun backPress_removesLastEntry() {
+  val backStack = mutableStateListOf<Any>(HomeKey, ProfileKey("u1"))
+  backStack.removeLastOrNull()
+  assertThat(backStack.last()).isEqualTo(HomeKey)
+}
+\`\`\`
+
+## Compose UI Test with Nav3
+
+\`\`\`kotlin
+@get:Rule val composeTestRule = createComposeRule()
+
+@Test
+fun clickingProfile_showsProfileScreen() {
+  val backStack = mutableStateListOf<Any>(HomeKey)
+
+  composeTestRule.setContent {
+    NavDisplay(
+      backStack = backStack,
+      entryProvider = entryProvider {
+        entry<HomeKey> { HomeScreen(onNavigateToProfile = { backStack.add(ProfileKey(it)) }) }
+        entry<ProfileKey> { key -> ProfileScreen(userId = key.userId) }
+      }
+    )
+  }
+
+  composeTestRule.onNodeWithTag("profileButton").performClick()
+  composeTestRule.onNodeWithText("Profile").assertIsDisplayed()
+  assertThat(backStack.last()).isInstanceOf(ProfileKey::class.java)
+}
+\`\`\`
+
+Source: https://developer.android.com/guide/navigation/navigation-3/testing
+`;
+    // ── Route dispatch ─────────────────────────────────────────────────────────
+    if (t.includes("scene") || t.includes("adaptive") || t.includes("pane") || t.includes("tablet")) {
+        return scenes;
+    }
+    if (t.includes("migrat") || t.includes("nav2") || t.includes("upgrade")) {
+        return migration;
+    }
+    if (t.includes("test")) {
+        return testing;
+    }
+    if (t.includes("key") || t.includes("backstack") || t.includes("back stack") || t.includes("display")) {
+        return overview;
+    }
+    // Default: overview + scenes summary
+    return overview + "\n\n---\n\n" + scenes.split("\n## What Scenes Does")[0] +
+        "\n\n## Quick Scenes Example\n" +
+        "For adaptive list-detail navigation, use `rememberListDetailSceneStrategy()` — " +
+        "the same back stack renders as single-pane on phones and two-pane on tablets.\n" +
+        "Query 'scenes' for the full example.\n\n" +
+        "**Other topics:** 'migration' (from Nav2), 'testing', 'scenes' (adaptive multi-pane)\n\n" +
+        "Source: https://developer.android.com/guide/navigation/navigation-3";
+}

package/build/tools/ondevice-ai.js

@@ -0,0 +1,283 @@
+// Tool 17: On-Device AI / AICore Guide
+// Android 16 shipped AICore and ML Kit Gen AI API — local LLMs on Android, no server round-trip.
+// Used by Gmail (Smart Reply), Google Photos (object detection), Pixel Screenshots (semantic search).
+// No MCP server covers this. AI tools default to cloud API calls when on-device is now the answer.
+export async function androidOnDeviceAiGuide(topic) {
+    const t = topic.toLowerCase().trim();
+    const overview = `
+# On-Device AI — Android AICore & ML Kit Gen AI (2025)
+Source: https://developer.android.com/ai/aicore
+Source: https://developers.google.com/ml-kit/genai
+
+## What On-Device AI Means in 2026
+
+Android 16 added AICore — a system-level service that manages on-device LLMs.
+ML Kit Gen AI API lets apps access these models through a standard interface.
+
+Key benefits vs cloud:
+- **Zero latency** — no network round-trip
+- **Privacy** — data never leaves the device
+- **Offline** — works without internet
+- **Cost** — no API billing
+
+## Which Google Apps Use It
+
+- **Gmail** — Smart Reply and Smart Compose on Pixel devices (on-device)
+- **Google Photos** — object detection, face grouping, on-device search
+- **Google Docs** — local summarization on Pixel
+- **Pixel Screenshots** — semantic search across screenshot history
+
+## Architecture Pattern — Repository Interface for Swappable Backends
+
+The official Google pattern: wrap ML models behind a repository interface so the
+implementation can switch between on-device (AICore) and cloud (Vertex AI) without
+touching the UI layer. This is the same MVVM/repository pattern you already know.
+
+\`\`\`kotlin
+// Domain layer — platform-agnostic interface
+interface AiTextRepository {
+  suspend fun summarize(text: String): Result<String>
+  suspend fun generateReply(context: String, options: List<String>): Result<String>
+  fun isAvailable(): Flow<Boolean>
+}
+
+// Data layer — on-device implementation
+class OnDeviceAiRepository(
+  private val generativeModel: GenerativeModel  // ML Kit Gen AI
+) : AiTextRepository {
+  override suspend fun summarize(text: String): Result<String> = runCatching {
+    val response = generativeModel.generateContent("Summarize: $text")
+    response.text ?: throw IllegalStateException("No response from on-device model")
+  }
+  override fun isAvailable(): Flow<Boolean> = flow {
+    emit(GenerativeModel.isAvailable())
+  }
+}
+
+// Data layer — cloud fallback implementation
+class CloudAiRepository(
+  private val vertexAi: FirebaseVertexAI
+) : AiTextRepository {
+  override suspend fun summarize(text: String): Result<String> = runCatching {
+    val model = vertexAi.generativeModel("gemini-2.0-flash")
+    val response = model.generateContent("Summarize: $text")
+    response.text ?: throw IllegalStateException("No response from cloud model")
+  }
+  override fun isAvailable(): Flow<Boolean> = flowOf(true) // Cloud always available (with network)
+}
+\`\`\`
+
+Source: https://developer.android.com/ai/aicore
+`;
+    const setup = `
+# On-Device AI — Setup & Initialization
+Source: https://developer.android.com/ml-kit/genai/on-device
+
+## Dependencies
+
+\`\`\`toml
+# libs.versions.toml
+[versions]
+mlkit-genai = "0.1.1"  # Check for latest at https://developers.google.com/ml-kit/genai
+
+[libraries]
+mlkit-genai-inference = { group = "com.google.mlkit", name = "genai-common", version.ref = "mlkit-genai" }
+\`\`\`
+
+\`\`\`kotlin
+// build.gradle.kts
+implementation(libs.mlkit.genai.inference)
+\`\`\`
+
+## Check Model Availability Before Use
+
+On-device models are only available on supported Pixel devices with the model downloaded.
+Always check availability and provide a fallback.
+
+\`\`\`kotlin
+// Check if on-device AI is available on this device
+class AiRepositoryFactory @Inject constructor(
+  @ApplicationContext private val context: Context,
+  private val cloudRepository: CloudAiRepository
+) {
+  suspend fun create(): AiTextRepository {
+    return if (isOnDeviceAvailable()) {
+      val model = GenerativeModel.getInstance(context)
+      OnDeviceAiRepository(model)
+    } else {
+      cloudRepository  // Graceful fallback to cloud
+    }
+  }
+
+  private suspend fun isOnDeviceAvailable(): Boolean {
+    return try {
+      GenerativeModel.isAvailable(context)
+    } catch (e: Exception) {
+      false
+    }
+  }
+}
+\`\`\`
+
+## ViewModel Integration
+
+\`\`\`kotlin
+@HiltViewModel
+class SummaryViewModel @Inject constructor(
+  private val aiRepository: AiTextRepository  // Interface — doesn't know if on-device or cloud
+) : ViewModel() {
+
+  private val _uiState = MutableStateFlow<SummaryUiState>(SummaryUiState.Idle)
+  val uiState: StateFlow<SummaryUiState> = _uiState.asStateFlow()
+
+  fun summarize(text: String) {
+    viewModelScope.launch {
+      _uiState.value = SummaryUiState.Loading
+      aiRepository.summarize(text)
+        .onSuccess { summary -> _uiState.value = SummaryUiState.Success(summary) }
+        .onFailure { error -> _uiState.value = SummaryUiState.Error(error.message) }
+    }
+  }
+}
+
+sealed interface SummaryUiState {
+  data object Idle : SummaryUiState
+  data object Loading : SummaryUiState
+  data class Success(val summary: String) : SummaryUiState
+  data class Error(val message: String?) : SummaryUiState
+}
+\`\`\`
+
+Source: https://developer.android.com/ml-kit/genai/on-device
+`;
+    const smartReply = `
+# On-Device AI — Smart Reply Pattern (Gmail-Style)
+Source: https://developers.google.com/ml-kit/genai/on-device
+
+## Smart Reply Implementation
+
+\`\`\`kotlin
+// Domain interface
+interface SmartReplyRepository {
+  suspend fun getSuggestedReplies(conversationHistory: List<Message>): Result<List<String>>
+}
+
+// On-device implementation using ML Kit
+class OnDeviceSmartReplyRepository @Inject constructor(
+  private val generativeModel: GenerativeModel
+) : SmartReplyRepository {
+
+  override suspend fun getSuggestedReplies(
+    conversationHistory: List<Message>
+  ): Result<List<String>> = runCatching {
+    val prompt = buildPrompt(conversationHistory)
+    val response = generativeModel.generateContent(prompt)
+
+    // Parse the structured response into reply options
+    response.text
+      ?.lines()
+      ?.filter { it.isNotBlank() }
+      ?.take(3)  // Limit to 3 suggestions like Gmail
+      ?: emptyList()
+  }
+
+  private fun buildPrompt(history: List<Message>): String {
+    val conversation = history.takeLast(5).joinToString("\n") { msg ->
+      "\${msg.sender}: \${msg.text}"
+    }
+    return """
+      Given this conversation:
+      $conversation
+
+      Suggest 3 short, natural reply options (one per line, no numbering, max 10 words each):
+    """.trimIndent()
+  }
+}
+
+// UI — chips that appear above keyboard
+@Composable
+fun SmartReplySuggestions(
+  suggestions: List<String>,
+  onSuggestionClick: (String) -> Unit
+) {
+  if (suggestions.isEmpty()) return
+
+  LazyRow(
+    horizontalArrangement = Arrangement.spacedBy(8.dp),
+    contentPadding = PaddingValues(horizontal = 16.dp)
+  ) {
+    items(suggestions) { suggestion ->
+      SuggestionChip(
+        onClick = { onSuggestionClick(suggestion) },
+        label = { Text(suggestion) }
+      )
+    }
+  }
+}
+\`\`\`
+
+Source: https://developers.google.com/ml-kit/genai
+`;
+    const mlKit = `
+# ML Kit — On-Device ML (Non-Generative)
+Source: https://developers.google.com/ml-kit
+
+## ML Kit vs AICore — When to Use Which
+
+| Use Case | Tool |
+|----------|------|
+| Text classification, entity extraction | ML Kit Text APIs |
+| Image labeling, object detection | ML Kit Vision APIs |
+| Face detection, pose estimation | ML Kit Vision APIs |
+| Barcode/QR scanning | ML Kit Barcode Scanning |
+| Translation | ML Kit Translation |
+| Free-form text generation, summarization, Q&A | AICore / ML Kit Gen AI |
+
+## Common ML Kit Setup
+
+\`\`\`toml
+[versions]
+mlkit = "19.0.3"
+
+[libraries]
+# Pick only what you need — each is a separate dependency
+mlkit-text-recognition = { group = "com.google.mlkit", name = "text-recognition", version.ref = "mlkit" }
+mlkit-image-labeling = { group = "com.google.mlkit", name = "image-labeling", version.ref = "mlkit" }
+mlkit-barcode-scanning = { group = "com.google.mlkit", name = "barcode-scanning", version.ref = "mlkit" }
+mlkit-face-detection = { group = "com.google.mlkit", name = "face-detection", version.ref = "mlkit" }
+mlkit-translation = { group = "com.google.mlkit", name = "translate", version.ref = "mlkit" }
+\`\`\`
+
+## Architecture Pattern — ML Models Behind Repository Interfaces
+
+\`\`\`kotlin
+// SAME pattern as AICore — ML models are implementation details, not domain concerns
+interface ImageAnalysisRepository {
+  suspend fun labelImage(bitmap: Bitmap): Result<List<String>>
+}
+
+class MlKitImageAnalysisRepository @Inject constructor() : ImageAnalysisRepository {
+  private val labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS)
+
+  override suspend fun labelImage(bitmap: Bitmap): Result<List<String>> = runCatching {
+    val inputImage = InputImage.fromBitmap(bitmap, 0)
+    labeler.process(inputImage).await()
+      .filter { it.confidence > 0.7f }
+      .map { it.text }
+  }
+}
+\`\`\`
+
+Source: https://developers.google.com/ml-kit
+`;
+    if (t.includes("smart reply") || t.includes("suggestion"))
+        return smartReply;
+    if (t.includes("setup") || t.includes("install") || t.includes("depend") || t.includes("init"))
+        return setup;
+    if (t.includes("ml kit") || t.includes("mlkit") || t.includes("vision") || t.includes("barcode") || t.includes("label"))
+        return mlKit;
+    return overview + "\n\n---\n\n" +
+        "**Query topics:** 'setup' (dependencies + initialization), 'smart reply' (Gmail-style suggestions), " +
+        "'ml kit' (non-generative on-device ML — vision, text, barcode)\n\n" +
+        "Source: https://developer.android.com/ai";
+}