androjack-mcp 1.3.0

package/src/tools/api-level.ts

@@ -0,0 +1,198 @@
+/**
+ * Tool 6 – android_api_level_check
+ *
+ * Maps API levels to version names, SDK integers, and market share.
+ * Prevents writing code that uses APIs unavailable at the project's minSdk.
+ * Zero network required — all data is embedded (fast + reliable).
+ */
+
+interface ApiLevelEntry {
+  versionName: string;
+  codename: string;
+  apiLevel: number;
+  releasedYear: number;
+  marketShareApprox?: string; // sourced from Android Studio distribution data
+  notableFeatures: string[];
+}
+
+// Source: https://developer.android.com/tools/releases/platforms
+// Updated through API 36 (Android 16, 2025)
+const API_LEVELS: ApiLevelEntry[] = [
+  {
+    versionName: "Android 16",
+    codename: "Baklava",
+    apiLevel: 36,
+    releasedYear: 2025,
+    notableFeatures: ["Predictive back gesture stable", "Health Connect updates", "Large screen optimizations"],
+  },
+  {
+    versionName: "Android 15",
+    codename: "VanillaIceCream",
+    apiLevel: 35,
+    releasedYear: 2024,
+    notableFeatures: ["Edge-to-edge enforcement", "NFC improvements", "Partial screen sharing"],
+  },
+  {
+    versionName: "Android 14",
+    codename: "UpsideDownCake",
+    apiLevel: 34,
+    releasedYear: 2023,
+    marketShareApprox: "~35%",
+    notableFeatures: ["Health Connect", "Photo picker", "Credential Manager"],
+  },
+  {
+    versionName: "Android 13",
+    codename: "Tiramisu",
+    apiLevel: 33,
+    releasedYear: 2022,
+    marketShareApprox: "~20%",
+    notableFeatures: ["Per-app language prefs", "Themed app icons", "Media permissions"],
+  },
+  {
+    versionName: "Android 12",
+    codename: "SnowCone",
+    apiLevel: 31,
+    releasedYear: 2021,
+    marketShareApprox: "~15%",
+    notableFeatures: ["Material You", "Splash screen API", "App hibernation"],
+  },
+  {
+    versionName: "Android 11",
+    codename: "RedVelvetCake",
+    apiLevel: 30,
+    releasedYear: 2020,
+    marketShareApprox: "~10%",
+    notableFeatures: ["One-time permissions", "Scoped storage enforced", "AsyncTask deprecated"],
+  },
+  {
+    versionName: "Android 10",
+    codename: "QuinceTart",
+    apiLevel: 29,
+    releasedYear: 2019,
+    marketShareApprox: "~8%",
+    notableFeatures: ["Dark theme", "Scoped storage", "Gesture navigation"],
+  },
+  {
+    versionName: "Android 9",
+    codename: "Pie",
+    apiLevel: 28,
+    releasedYear: 2018,
+    notableFeatures: ["Wi-Fi RTT", "Display cutout support", "Neural Networks API 1.1"],
+  },
+  {
+    versionName: "Android 8.0",
+    codename: "Oreo",
+    apiLevel: 26,
+    releasedYear: 2017,
+    notableFeatures: ["Notification channels (REQUIRED)", "Picture-in-picture", "Autofill"],
+  },
+  {
+    versionName: "Android 7.0",
+    codename: "Nougat",
+    apiLevel: 24,
+    releasedYear: 2016,
+    notableFeatures: ["Multi-window", "Direct reply notifications", "Doze improvements"],
+  },
+  {
+    versionName: "Android 6.0",
+    codename: "Marshmallow",
+    apiLevel: 23,
+    releasedYear: 2015,
+    notableFeatures: ["Runtime permissions (REQUIRED)", "Fingerprint API", "Doze mode"],
+  },
+  {
+    versionName: "Android 5.0",
+    codename: "Lollipop",
+    apiLevel: 21,
+    releasedYear: 2014,
+    notableFeatures: ["Material Design", "ART runtime default", "Vector drawables"],
+  },
+];
+
+function findByApiLevel(level: number): ApiLevelEntry | undefined {
+  return API_LEVELS.find((e) => e.apiLevel === level);
+}
+
+function findByName(name: string): ApiLevelEntry | undefined {
+  const lower = name.toLowerCase();
+  return API_LEVELS.find(
+    (e) =>
+      e.versionName.toLowerCase().includes(lower) ||
+      e.codename.toLowerCase().includes(lower)
+  );
+}
+
+/**
+ * Checks what APIs are available at a given minSdk level and warns about
+ * common pitfalls.
+ */
+function getMinSdkWarnings(minSdk: number): string[] {
+  const warnings: string[] = [];
+
+  if (minSdk < 26) warnings.push("⚠️ API < 26: Notification channels not available (required for foreground services on Android 8+)");
+  if (minSdk < 23) warnings.push("⚠️ API < 23: Runtime permissions not available — you must handle permission dialogs manually");
+  if (minSdk < 21) warnings.push("⚠️ API < 21: Material Design components and VectorDrawable support limited");
+  if (minSdk >= 21) warnings.push("✅ API 21+: Jetpack Compose minimum supported");
+  if (minSdk >= 23) warnings.push("✅ API 23+: Safe to use runtime permissions API directly");
+  if (minSdk >= 26) warnings.push("✅ API 26+: Notification channels required and available");
+
+  return warnings;
+}
+
+/**
+ * Core handler for android_api_level_check tool.
+ */
+export function androidApiLevelCheck(input: string): string {
+  const trimmed = input.trim();
+
+  // Numeric API level input
+  const numeric = parseInt(trimmed, 10);
+  if (!isNaN(numeric)) {
+    const entry = findByApiLevel(numeric);
+    if (!entry) {
+      const closest = API_LEVELS.reduce((prev, curr) =>
+        Math.abs(curr.apiLevel - numeric) < Math.abs(prev.apiLevel - numeric) ? curr : prev
+      );
+      return (
+        `## AndroJack API Level Check\n**Input:** API ${numeric}\n\n` +
+        `❓ API level ${numeric} not in local registry.\n` +
+        `Closest known: **${closest.versionName} (API ${closest.apiLevel})**\n\n` +
+        `Check: https://developer.android.com/tools/releases/platforms`
+      );
+    }
+
+    const warnings = getMinSdkWarnings(numeric);
+    return (
+      `## AndroJack API Level Check\n\n` +
+      `| Field | Value |\n|---|---|\n` +
+      `| Version | ${entry.versionName} |\n` +
+      `| Codename | ${entry.codename} |\n` +
+      `| API Level | ${entry.apiLevel} |\n` +
+      `| Released | ${entry.releasedYear} |\n` +
+      (entry.marketShareApprox ? `| Market Share | ${entry.marketShareApprox} |\n` : "") +
+      `\n**Notable Features:**\n${entry.notableFeatures.map((f) => `- ${f}`).join("\n")}\n\n` +
+      `**minSdk Guidance:**\n${warnings.join("\n")}\n\n` +
+      `**Official Reference:** https://developer.android.com/tools/releases/platforms\n\n` +
+      `> ℹ️ Use \`compileSdk ${Math.max(entry.apiLevel, 35)}\` and set \`minSdk\` based on your audience.`
+    );
+  }
+
+  // Text input (version name or codename)
+  const entry = findByName(trimmed);
+  if (entry) {
+    return androidApiLevelCheck(String(entry.apiLevel));
+  }
+
+  // Full table fallback
+  const table =
+    `## Android API Level Reference\n\n` +
+    `| Version | Codename | API | Year | Market Share |\n|---|---|---|---|---|\n` +
+    API_LEVELS.map(
+      (e) =>
+        `| ${e.versionName} | ${e.codename} | ${e.apiLevel} | ${e.releasedYear} | ${e.marketShareApprox ?? "—"} |`
+    ).join("\n") +
+    `\n\n**Recommended minSdk for new apps:** API 26+ (covers ~90%+ of active devices)\n` +
+    `**Official Reference:** https://developer.android.com/tools/releases/platforms`;
+
+  return table;
+}

package/src/tools/api36-compliance.ts

@@ -0,0 +1,289 @@
+// Tool 15: Android 16 / API 36 Compliance Checker
+// Google Play mandate: all apps must target API 36 by August 2026.
+// Android 16 removed the ability to lock orientation or restrict resizability on ≥600dp devices.
+
+export async function androidApi36Compliance(topic: string): Promise<string> {
+  const t = topic.toLowerCase().trim();
+
+  const overview = `
+# Android 16 / API 36 Compliance Reference
+Source: https://developer.android.com/about/versions/16/behavior-changes-all
+
+## The Mandate
+
+Google Play requires all apps to **target API 36 by August 2026**.
+Android 16 (API 36) introduced breaking changes for large-screen device behavior.
+Apps that fail compliance checks will receive warning badges in Play Store listings
+and may be demoted in search results.
+
+## What Changed in Android 16 — The Breaking Rules
+
+### 1. Mandatory Resizability on Large Screens (≥600dp)
+On devices with width ≥600dp (tablets, foldables, ChromeOS), apps can NO LONGER:
+- Lock screen orientation
+- Restrict aspect ratio
+- Disable multi-window/resizability
+
+The platform **overrides** these flags on ≥600dp devices. Apps must handle any aspect ratio.
+
+### 2. Predictive Back — Required for API 36 Targets
+Apps targeting API 36 must implement Predictive Back Gesture.
+The legacy \`OnBackPressedCallback\` alone is insufficient — use \`BackHandler\` in Compose
+or the \`OnBackPressedDispatcher\` with \`createOnBackPressedCallback { }\`.
+
+### 3. 16 KB Page Size — Native Code
+Apps with native (NDK/JNI) libraries must be compiled for 16 KB memory page alignment.
+Android Studio shows a lint warning for non-compliant APKs. Failure = crash on affected hardware.
+
+## ❌ Manifest Flags That Now FAIL on Large Screens
+
+\`\`\`xml
+<!-- ❌ ILLEGAL on ≥600dp devices in Android 16 -->
+<activity
+  android:screenOrientation="portrait"
+  android:screenOrientation="landscape"
+  android:screenOrientation="sensorPortrait"
+  android:resizeableActivity="false"
+  android:maxAspectRatio="1.86"   <!-- Restricts to phone ratio — illegal on large screens -->
+/>
+\`\`\`
+
+## ✅ Correct Manifest for API 36 Compliance
+
+\`\`\`xml
+<activity
+  android:name=".MainActivity"
+  android:exported="true"
+  android:windowSoftInputMode="adjustResize"
+  <!-- NO screenOrientation — let the system decide -->
+  <!-- NO resizeableActivity="false" -->
+  <!-- NO maxAspectRatio restriction -->
+>
+\`\`\`
+
+## Games Exception
+
+Games are exempt from the mandatory resizability requirement if declared:
+\`\`\`xml
+<application android:appCategory="game">
+\`\`\`
+Users can also opt individual apps into their preferred behavior via device settings.
+
+Source: https://developer.android.com/about/versions/16/behavior-changes-all#large-screen
+`;
+
+  const layouts = `
+# Android 16 — Canonical Adaptive Layout Patterns
+Source: https://developer.android.com/guide/topics/large-screens/support-different-screen-sizes
+
+## The Four Canonical Layouts (Google's Reference Implementations)
+
+### 1. List-Detail (Gmail, Messages)
+\`\`\`kotlin
+// Use Navigation 3 + Scenes API for List-Detail
+// Or use ListDetailPaneScaffold from Material3 Adaptive
+implementation("androidx.compose.material3.adaptive:adaptive:1.1.0")
+implementation("androidx.compose.material3.adaptive:adaptive-navigation:1.1.0")
+
+@Composable
+fun MailApp() {
+  val navigator = rememberListDetailPaneScaffoldNavigator<String>()
+  ListDetailPaneScaffold(
+    directive = navigator.scaffoldDirective,
+    value = navigator.scaffoldValue,
+    listPane = {
+      InboxPane(onEmailClick = { id ->
+        navigator.navigateTo(ListDetailPaneScaffoldRole.Detail, id)
+      })
+    },
+    detailPane = {
+      val emailId = navigator.currentDestination?.content
+      if (emailId != null) EmailDetailPane(emailId)
+      else EmptyDetailPane()
+    }
+  )
+}
+\`\`\`
+
+### 2. Feed (Photos, Play Store)
+\`\`\`kotlin
+// Adaptive grid — columns based on WindowWidthSizeClass
+@Composable
+fun AdaptiveFeed(items: List<Item>) {
+  val windowInfo = currentWindowAdaptiveInfo()
+  val columns = when (windowInfo.windowSizeClass.windowWidthSizeClass) {
+    WindowWidthSizeClass.COMPACT  -> 1
+    WindowWidthSizeClass.MEDIUM   -> 2
+    WindowWidthSizeClass.EXPANDED -> 3
+    else -> 1
+  }
+  LazyVerticalGrid(columns = GridCells.Fixed(columns)) {
+    items(items) { item -> FeedCard(item) }
+  }
+}
+\`\`\`
+
+### 3. Supporting Pane (Docs, Sheets)
+\`\`\`kotlin
+// Primary content + persistent tool panel on large screens
+// SupportingPaneScaffold from Material3 Adaptive
+@Composable
+fun DocumentEditor() {
+  val navigator = rememberSupportingPaneScaffoldNavigator()
+  SupportingPaneScaffold(
+    directive = navigator.scaffoldDirective,
+    value = navigator.scaffoldValue,
+    mainPane = { DocumentContent() },
+    supportingPane = { FormattingPanel() }
+  )
+}
+\`\`\`
+
+### 4. Navigation Suite Scaffold (automatic chrome switching)
+\`\`\`kotlin
+// Single API — auto-switches BottomBar → Rail → Drawer based on window size
+@Composable
+fun AppWithAdaptiveNav(content: @Composable () -> Unit) {
+  NavigationSuiteScaffold(
+    navigationSuiteItems = {
+      AppDestination.entries.forEach { destination ->
+        item(
+          icon = { Icon(destination.icon, contentDescription = destination.label) },
+          label = { Text(destination.label) },
+          selected = currentDestination == destination,
+          onClick = { /* navigate */ }
+        )
+      }
+    }
+  ) {
+    content()
+  }
+}
+\`\`\`
+
+Source: https://developer.android.com/guide/topics/large-screens/canonical-app-layouts
+`;
+
+  const checklist = `
+# Android 16 Compliance Checklist — Play Store Large-Screen Quality Tiers
+Source: https://developer.android.com/docs/quality-guidelines/large-screen-app-quality
+
+## Tier 3: Large Screen Ready (Minimum — required to avoid warning badge)
+- [ ] No fixed orientation locks (no \`screenOrientation\` in manifest)
+- [ ] No \`resizeableActivity="false"\`
+- [ ] No hardcoded aspect ratio restrictions (\`maxAspectRatio\`)
+- [ ] App does not crash or lose data on configuration change (rotation, resize)
+- [ ] Keyboard/mouse basic support (for ChromeOS)
+- [ ] Multi-window does not break app functionality
+
+## Tier 2: Large Screen Optimized
+Everything in Tier 3, plus:
+- [ ] Adaptive layouts using WindowSizeClass breakpoints
+- [ ] NavigationSuiteScaffold (auto-switches nav chrome by window size)
+- [ ] No content clipped or unreachable in landscape/large screen
+- [ ] Proper inset handling (\`WindowInsets\`, \`safeDrawing\`, \`imePadding\`)
+
+## Tier 1: Large Screen Differentiated (Editors' Choice eligible)
+Everything in Tier 2, plus:
+- [ ] Multi-pane layout using ListDetailPaneScaffold or Nav3 Scenes
+- [ ] Foldable hinge awareness (FoldingFeature API)
+- [ ] Drag-and-drop support between panes
+- [ ] App-level keyboard shortcuts
+- [ ] Contextual menus on right-click
+
+## Critical Code Patterns for Compliance
+
+### Configuration Change Survival
+\`\`\`kotlin
+// ViewModel automatically survives rotation — use it
+class MyViewModel : ViewModel() {
+  val uiState: StateFlow<MyUiState> = ...
+}
+
+// For non-ViewModel state, use rememberSaveable
+var selectedId by rememberSaveable { mutableStateOf<String?>(null) }
+\`\`\`
+
+### Inset Handling (Required — no content behind nav bars)
+\`\`\`kotlin
+Scaffold(
+  modifier = Modifier.fillMaxSize()
+) { paddingValues ->
+  LazyColumn(
+    contentPadding = paddingValues, // ALWAYS pass scaffold padding
+    modifier = Modifier.imePadding() // keyboard avoidance
+  ) { ... }
+}
+\`\`\`
+
+### WindowSizeClass — The Correct Import (not the deprecated one)
+\`\`\`kotlin
+// ✅ Correct — currentWindowAdaptiveInfo() from WindowManager
+val adaptiveInfo = currentWindowAdaptiveInfo()
+val widthClass = adaptiveInfo.windowSizeClass.windowWidthSizeClass
+
+// ❌ Deprecated — calculateWindowSizeClass(activity) is the old API
+\`\`\`
+
+Source: https://developer.android.com/docs/quality-guidelines/large-screen-app-quality
+`;
+
+  const predictiveBack = `
+# Android 16 — Predictive Back Gesture (Required for API 36)
+Source: https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture
+
+## What Changed
+
+Predictive Back is mandatory for apps targeting API 36. The system now previews
+the "behind" screen during a back swipe before the user completes it.
+
+## Implementation in Compose
+
+\`\`\`kotlin
+// In AndroidManifest.xml — opt in (required for API 33-35, automatic for API 36)
+<application android:enableOnBackInvokedCallback="true">
+
+// In Compose — BackHandler handles predictive back correctly
+@Composable
+fun ScreenWithCustomBack(onBack: () -> Unit) {
+  BackHandler(enabled = true) {
+    // Custom back logic — e.g., close drawer before popping screen
+    onBack()
+  }
+}
+\`\`\`
+
+## Predictive Back for Multi-Step Flows
+\`\`\`kotlin
+@Composable
+fun MultiStepForm(currentStep: Int, onStepBack: () -> Unit, onExit: () -> Unit) {
+  BackHandler(enabled = currentStep > 0) {
+    onStepBack() // Go to previous step, not previous screen
+  }
+  // When currentStep == 0, BackHandler is disabled → system handles back → pops screen
+}
+\`\`\`
+
+## Navigation 3 — Predictive Back is Automatic
+When using Navigation 3 (rememberNavBackStack + NavDisplay), predictive back works
+out of the box — NavDisplay registers a BackHandler that removes the last entry.
+No extra setup required.
+
+Source: https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture
+`;
+
+  if (t.includes("layout") || t.includes("pane") || t.includes("adaptive") || t.includes("canonical")) {
+    return layouts;
+  }
+  if (t.includes("checklist") || t.includes("quality") || t.includes("tier") || t.includes("play store")) {
+    return checklist;
+  }
+  if (t.includes("back") || t.includes("predictive")) {
+    return predictiveBack;
+  }
+
+  return overview + "\n\n---\n\n" +
+    "**Query topics:** 'layouts' (canonical adaptive patterns), 'checklist' (Play Store quality tiers), " +
+    "'predictive back' (API 36 back gesture requirement), 'page size' (16 KB native alignment)\n\n" +
+    "Source: https://developer.android.com/about/versions/16";
+}

package/src/tools/architecture.ts

@@ -0,0 +1,94 @@
+/**
+ * Tool 3 – architecture_reference
+ *
+ * Retrieves official Android architecture guide content for a given topic.
+ * The AI MUST call this before suggesting project structure, patterns,
+ * or Jetpack component relationships.
+ */
+
+import { ARCHITECTURE_GUIDES } from "../constants.js";
+import { secureFetch, extractPageText } from "../http.js";
+
+function findGuideUrl(topic: string): string | null {
+  const lower = topic.toLowerCase().trim();
+
+  // Exact key match
+  if (ARCHITECTURE_GUIDES[lower]) return ARCHITECTURE_GUIDES[lower];
+
+  // Partial key match
+  for (const [key, url] of Object.entries(ARCHITECTURE_GUIDES)) {
+    if (lower.includes(key) || key.includes(lower)) return url;
+  }
+
+  return null;
+}
+
+/**
+ * Core handler for architecture_reference tool.
+ */
+export async function architectureReference(topic: string): Promise<string> {
+  if (!topic || topic.trim().length < 2) {
+    return "ERROR: Topic must be at least 2 characters.";
+  }
+
+  const sanitized = topic.trim().slice(0, 200);
+  const guideUrl = findGuideUrl(sanitized);
+
+  const header =
+    `## AndroJack Architecture Reference\n` +
+    `**Topic:** "${sanitized}"\n\n`;
+
+  if (!guideUrl) {
+    // Fallback: search developer.android.com
+    const searchUrl = `https://developer.android.com/s/results?q=${encodeURIComponent(sanitized)}`;
+    try {
+      const html = await secureFetch(searchUrl);
+      const text = extractPageText(html, 2500);
+      return (
+        header +
+        `**No direct guide mapped. Showing search results from developer.android.com:**\n` +
+        `**URL:** ${searchUrl}\n\n` +
+        text +
+        `\n\n> 📐 GROUNDING GATE: Review the architecture guide above before proposing any structure.`
+      );
+    } catch (err) {
+      return (
+        header +
+        `Could not fetch guide. Search manually: ${searchUrl}\n` +
+        `Error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  try {
+    const html = await secureFetch(guideUrl);
+    const text = extractPageText(html, 3000);
+
+    return (
+      header +
+      `**Official Guide:** ${guideUrl}\n\n` +
+      text +
+      `\n\n---\n` +
+      `> 📐 GROUNDING GATE: Architecture code must align with the official guide above.`
+    );
+  } catch (err) {
+    return (
+      header +
+      `**Official Guide:** ${guideUrl}\n` +
+      `**Fetch failed:** ${err instanceof Error ? err.message : String(err)}\n\n` +
+      `Please open the guide manually: ${guideUrl}`
+    );
+  }
+}
+
+/**
+ * Returns the full list of supported architecture topics for discovery.
+ */
+export function listArchitectureTopics(): string {
+  const topics = Object.keys(ARCHITECTURE_GUIDES).sort();
+  return (
+    `## Supported Architecture Topics\n\n` +
+    topics.map((t) => `- \`${t}\``).join("\n") +
+    `\n\nPass any of these to \`architecture_reference\` for official guide content.`
+  );
+}