@leejungkiin/awkit 1.0.7 → 1.0.9

package/skills/smali-to-kotlin/phase-0-discovery.md

@@ -1,129 +1,128 @@
-# 🔍 Phase 0: Discovery (Satellite View) — Android
+# 🗺️ Phase 0: Discovery (Satellite View)
 
-> **Zoom Level:** 0 — Toàn cảnh
-> **Goal:** Understand the app: structure, libraries, components, screen flow.
-> **Output:** App Map document (`app-map.md`)
+> **Zoom Level:** 0 — Bird's Eye
+> **Goal:** Create an "App Map" — understand WHAT the app is and WHAT it contains.
+> **Output:** Diagrams, tables, maps. **NO CODE.**
 
 ---
 
 ## ⛔ OUTPUT RULE
 
 ```
-✅ ALLOWED: Diagrams, tables, lists, reports
-✅ ALLOWED: Shell commands for scanning
-❌ BLOCKED: Any Kotlin code
-❌ BLOCKED: Any implementation decisions (those come in Phase 1)
+✅ ALLOWED: ASCII diagrams, Mermaid, tables, bullet lists, bash scan commands
+❌ BLOCKED: Kotlin/Java code, function signatures, class definitions
 ```
 
 ---
 
 ## 📋 Sub-steps
 
-### 0.1: Scan APK Structure
+### 0.1: Confirm Input
 
-Verify Apktool output structure:
 ```
-[apktool_dir]/
-├── AndroidManifest.xml     ← Entry point
-├── smali/                  ← Decompiled bytecode
-├── res/                    ← Resources (layouts, drawables, strings...)
-├── assets/                 ← Raw assets (ML models, configs...)
-├── lib/                    ← Native libraries (.so)
-└── original/               ← Original META-INF
+🔧 Android Reverse Engineering bắt đầu!
+
+Em cần biết:
+1. Thư mục Apktool output ở đâu?
+2. Tên app gốc? Package name?
+
+Chưa chạy Apktool? → apktool d your-app.apk -o ./decompiled/
+```
+
+### 0.2: Structure Scan
+
+Quét folder structure để hiểu quy mô app:
+
+```bash
+# Top-level packages (app code vs libraries)
+find [apktool_dir]/smali -maxdepth 3 -type d | sed 's|.*/smali/||' | sort
+
+# Multi-dex check
+find [apktool_dir] -name "smali*" -maxdepth 1 -type d
+
+# Resource overview
+ls [apktool_dir]/res/layout/ | wc -l         # Number of layouts
+ls [apktool_dir]/res/drawable*/ | wc -l       # Number of drawables
+cat [apktool_dir]/res/values/strings.xml | grep '<string' | wc -l  # Strings count
+```
+
+### 0.3: Library Detection
+
+Quét smali directories để nhận diện thư viện. Ref: `library-patterns.md`
+
+```bash
+# Known library packages
+find [apktool_dir]/smali -maxdepth 3 -type d | grep -E "(google|facebook|squareup|airbnb|bumptech|jakewharton|reactivex|greenrobot)" | sort
+
+# Native libraries
+find [apktool_dir]/lib -name "*.so" 2>/dev/null
+
+# Assets (ML models, WebView, configs)
+ls [apktool_dir]/assets/ 2>/dev/null
+```
+
+**Phân loại thành 5 nhóm:**
+
+| Category | Meaning | Action |
+|----------|---------|--------|
+| ✅ Reuse | Modern, still maintained | Add to build.gradle |
+| 🔄 Replace | Legacy/deprecated | Map to modern replacement |
+| 🔵 Firebase/Google | Platform SDKs | Use latest version |
+| 📱 Native (.so) | JNI libraries | Keep, create bridge |
+| 🏷️ App Code | Original app logic | Rebuild in Kotlin |
+
+### 0.4: Manifest Analysis
+
+```bash
+cat [apktool_dir]/AndroidManifest.xml
 ```
 
-### 0.2: Library Scanner
-
-Scan ALL dependencies before any coding:
-
-1. **Scan `smali/` directories** for package patterns:
-   ```
-   smali/com/google/      → Google SDKs
-   smali/com/facebook/    → Facebook SDK
-   smali/com/squareup/    → OkHttp, Retrofit, Picasso
-   smali/io/reactivex/    → RxJava
-   smali/org/greenrobot/  → EventBus
-   smali/com/bumptech/    → Glide
-   smali/com/airbnb/      → Lottie
-   smali/androidx/         → AndroidX (baseline)
-   smali/com/jakewharton/ → Butterknife, Timber
-   ```
-
-2. **Check `lib/` for native libraries (.so)**:
-   ```
-   lib/arm64-v8a/*.so     → 64-bit native libs
-   lib/armeabi-v7a/*.so   → 32-bit native libs
-   ```
-
-3. **Check `assets/` for embedded resources:**
-   - ML models (.tflite, .onnx)
-   - WebView HTML/JS bundles
-   - Config files (JSON, XML)
-
-4. **Output: Library Detection Report** — see `library-patterns.md` for comprehensive patterns.
-
-### 0.3: AndroidManifest Analysis
-
-Extract from `AndroidManifest.xml`:
-
-1. Application ID (`package` attribute)
-2. Min/Target SDK versions
-3. Permissions (group by category: network, storage, camera, etc.)
-4. Entry points:
-   - `Application` class (custom init?)
-   - Launcher Activity (SplashActivity? MainActivity?)
-5. All components:
-   - Activities → future Compose screens
-   - Services → WorkManager candidates?
-   - BroadcastReceivers → keep or replace with Flow?
-   - ContentProviders → keep or replace with Room?
-6. Intent-filters and deep links
-
-### 0.4: Screen Flow Map
-
-Map navigation based on Activities:
-
-```mermaid
-graph LR
-    Splash --> Login
-    Login --> MainTab
-    MainTab --> Home
-    MainTab --> Search
-    MainTab --> Profile
-    Home --> Detail
-    Profile --> Settings
+Extract:
+- Application ID + Package name
+- Min/Target SDK
+- Permissions (grouped by category)
+- Entry points: Application class, Launcher Activity
+- All components: Activities, Services, Receivers, Providers
+- Deep links / Intent filters
+
+### 0.5: Screen Map
+
+Map Activities → future Compose screens. Draw navigation flow:
+
+```
+Activities found → Group by feature → Draw screen graph
 ```
 
-### 0.5: Complexity Estimate
+### 0.6: Complexity Estimate
 
-| Area | Rating | Notes |
-|------|--------|-------|
-| Data Layer | ●●●○○ | [N] APIs, [N] DB tables, [N] DataStores |
-| Core Logic | ●●○○○ | [N] crypto utils, [N] formatters |
-| UI Screens | ●●●●○ | [N] screens, [N] complex layouts |
-| SDK Integration | ●●○○○ | [N] third-party, [N] native libs |
+Rate each area 1-5 dots:
+- Data Layer: ●●●○○ (APIs, DB, preferences)
+- Core Logic: ●●○○○ (crypto, formatters, utils)
+- UI Screens: ●●●●○ (screen count, complex layouts)
+- SDK Integration: ●●○○○ (third-party, native libs)
 
 ---
 
 ## 📊 Output: App Map
 
-Use template from `templates/app-map.md`.
+Use template from `templates/app-map.md`. Must include:
+
+1. **Identity** — package, SDK levels, screen count
+2. **Screen Flow** — navigation graph (ASCII or Mermaid)
+3. **Library Landscape** — categorized dependency list
+4. **Complexity Estimate** — visual dots rating
+5. **Key Observations** — anything notable (obfuscation, unusual patterns)
 
 ---
 
 ## ✅ Gate
 
 ```
-"🗺️ App Map xong. Anh review:
-- [N] screens detected
-- [N] libraries found ([N] reuse, [N] replace)
-- [N] native libs
-- Complexity: [Low/Medium/High]
-
-Có gì cần điều chỉnh không?
-→ OK → Phase 1 (Architecture Design)"
+"🗺️ Đây là App Map. Anh review xem có gì cần diều chỉnh không?"
+→ User approves → Proceed to Phase 1 (Architecture)
+→ User has questions → Investigate and update map
 ```
 
 ---
 
-*Phase 0: Discovery — Know your target before you build*
+*Phase 0: Discovery — No code, just understanding*

package/skills/smali-to-kotlin/phase-1-architecture.md

@@ -1,19 +1,19 @@
-# 🏗️ Phase 1: Architecture (District View) — Android
+# 🏗️ Phase 1: Architecture (District View)
 
 > **Zoom Level:** 1 — Architecture Design
-> **Goal:** Design overall architecture with UI-First build order. NO code bodies.
+> **Goal:** Design the overall architecture BEFORE writing any code.
 > **Input:** Completed App Map from Phase 0.
-> **Output:** Architecture Blueprint document.
+> **Output:** Architecture Blueprint (layer maps, feature tables, API list). **NO CODE BODIES.**
 
 ---
 
 ## ⛔ OUTPUT RULE
 
 ```
-✅ ALLOWED: Architecture diagrams, layer maps, feature-to-file mapping, API endpoint tables
+✅ ALLOWED: Architecture diagrams, layer maps, feature-to-file mapping tables, API endpoint tables
 ✅ ALLOWED: File paths, package names, dependency lists
-⚠️ ALLOWED: build.gradle.kts skeleton (plugins + dependencies only)
 ❌ BLOCKED: Function bodies, implementation details, actual Kotlin code
+⚠️ EXCEPTION: build.gradle.kts skeleton (plugin + dependency declarations only)
 ```
 
 ---
@@ -22,113 +22,116 @@
 
 ### 1.1: Layer Design
 
+Design Clean Architecture layers based on App Map:
+
 ```
 ┌─────────────────────────────────────┐
 │ Presentation                        │
 │ ├── screens/ ([N] screens)          │
 │ ├── navigation/ (NavGraph)          │
-│ ├── theme/ (Material 3)             │
-│ └── components/ (Shared composables)│
+│ └── theme/ (Material3)             │
 ├─────────────────────────────────────┤
 │ Domain                              │
 │ ├── model/ ([N] business models)    │
-│ ├── repository/ ([N] interfaces)    │
+│ ├── repository/ ([N] interfaces)   │
 │ └── usecase/ ([N] use cases)        │
 ├─────────────────────────────────────┤
 │ Data                                │
-│ ├── remote/ ([N] API services)      │
-│ ├── local/ (Room, DataStore)        │
-│ └── repository/ (implementations)   │
+│ ├── remote/ ([N] API services)     │
+│ ├── local/ (Room, DataStore)       │
+│ └── repository/ (implementations)  │
 ├─────────────────────────────────────┤
-│ DI / Utilities                      │
-│ └── modules, extensions, crypto     │
+│ DI                                  │
+│ └── modules/ (Network, DB, Repo)   │
 └─────────────────────────────────────┘
 ```
 
 ### 1.2: Feature → File Mapping
 
+Map each feature to its Clean Architecture components:
+
 | Feature | Domain Model | Repository | UseCase | Screen | ViewModel |
 |---------|-------------|-----------|---------|--------|-----------|
 | Auth | User, Token | AuthRepo | LoginUC | Login | AuthVM |
-| Home | Feed | HomeRepo | GetFeedUC | Home | HomeVM |
+| Home | Data | HomeRepo | GetDataUC | Home | HomeVM |
 | ... | ... | ... | ... | ... | ... |
 
 ### 1.3: API Endpoint Inventory
 
+Extract ALL API endpoints from Smali analysis:
+
 | # | Method | Endpoint | Auth | Request | Response | Notes |
 |---|--------|----------|------|---------|----------|-------|
-| 1 | POST | /auth/login | No | email, pwd | JWT | - |
-| 2 | GET | /users/me | Bearer | - | User | - |
+| 1 | POST | /auth/login | No | email, pwd | JWT token | - |
+| 2 | GET | /users/me | Bearer | - | User object | - |
 
 **How to find in Smali:**
 ```
-const-string → "https://" or "http://" (base URL)
-.field → BASE_URL, API_URL
-StringBuilder + append (endpoint construction)
-Annotation patterns (@GET, @POST in retrofit)
+Look for: const-string → "https://" or "http://"
+Look for: .field → BASE_URL, API_URL
+Look for: StringBuilder + append patterns (endpoint construction)
+Look for: annotation patterns (@GET, @POST in okhttp/retrofit)
 ```
 
 ### 1.4: Data Schema Inventory
 
-| Model | Key Fields | Source | Storage |
-|-------|-----------|--------|---------|
+List ALL data structures found:
+
+| Model | Fields (key ones) | Source | Storage |
+|-------|-------------------|--------|---------|
 | User | id, name, email, avatar | API | Room + Memory |
-| Settings | theme, language | Local | DataStore |
+| Settings | theme, language, notifications | Local | DataStore |
 
 ### 1.5: Project Structure
 
+Propose directory structure based on features:
+
 ```
 app/src/main/java/com/package/
 ├── App.kt
 ├── di/ (AppModule, NetworkModule, DatabaseModule)
 ├── data/
-│   ├── remote/api/
-│   ├── remote/dto/
-│   ├── local/db/
-│   ├── local/datastore/
-│   └── repository/
+│   ├── remote/api/ ([N] Retrofit interfaces)
+│   ├── remote/dto/ (DTOs)
+│   ├── local/db/ (Room)
+│   ├── local/datastore/ (DataStore)
+│   └── repository/ (Implementations)
 ├── domain/
-│   ├── model/
-│   ├── repository/
-│   └── usecase/
+│   ├── model/ (Business models)
+│   ├── repository/ (Interfaces)
+│   └── usecase/ (Use cases)
 ├── presentation/
-│   ├── navigation/
-│   ├── theme/
-│   ├── components/
+│   ├── navigation/ (NavGraph, Routes)
+│   ├── theme/ (Colors, Typography, Theme)
+│   ├── components/ (Shared composables)
 │   └── screens/
 │       ├── splash/
 │       ├── auth/
 │       ├── home/
 │       └── [feature]/
-└── util/
+└── util/ (Extensions, helpers)
 ```
 
-### 1.6: Build Order (UI-First) ⭐
+### 1.6: Build Order Suggestion
 
-> **IMPORTANT:** UI-First build order — design and approve UI before coding logic.
+Recommend order based on dependency graph:
 
 ```
-Foundation (one-time):
-  1. 🟢 Project setup + DI skeleton + Theme/Design System
-  2. 🟢 Navigation structure (routes, tab bar)
-
-Per Feature (repeat for each):
-  3. 📐 Blueprint: Contracts (models, repos, use cases, state)
-  4. 🎨 UI Shell: Visual implementation + Resource extraction
-  5. 🚦 GATE: User approve UI
-  6. 🔨 Logic: Domain → Data → ViewModel → Wire UI
-  7. 🧪 Test: Integration + Parity
-
-Final (one-time):
-  8. 📦 SDK Integration + Native libs
-  9. ✅ Full Parity Check
+1. 🟢 Project setup + DI skeleton + Theme
+2. 🟢 Domain models (data classes — no logic)
+3. 🟡 Data layer (API interfaces + Room entities)
+4. 🟡 Core utils (crypto, formatters — need parity testing)
+5. 🔴 UI screens (per-feature, starting from auth)
+6. 🔴 SDK integration + Parity check
 ```
 
 ### 1.7: Tech Stack Decisions
 
+Confirm decisions from Phase 0 Library Report:
+
 | Decision | Choice | Rationale |
 |----------|--------|-----------|
-| Image Loading | Coil | Modern, Compose-native |
+| Image Loading | Coil (replace Glide) | Modern, Compose-native |
 | JSON | Kotlin Serialization | Type-safe, no reflection |
 | ... | ... | ... |
 
@@ -136,22 +139,28 @@ Final (one-time):
 
 ## 📊 Output: Architecture Blueprint
 
-Use template from `templates/architecture.md`.
+Use template from `templates/architecture.md`. Must include:
+
+1. **Layer Map** — ASCII architecture diagram with counts
+2. **Feature Table** — feature → file mapping
+3. **API Inventory** — all endpoints found
+4. **Data Schema** — all models with key fields
+5. **Project Structure** — proposed directory tree
+6. **Build Order** — suggested implementation sequence
+7. **Tech Decisions** — confirmed choices
 
 ---
 
 ## ✅ Gate
 
 ```
-"🏗️ Architecture Blueprint xong.
-Build order: UI-First per feature.
-Anh muốn bắt đầu từ feature nào?
+"🏗️ Architecture Blueprint xong. Anh muốn bắt đầu từ feature nào?
 Em suggest: [Feature X] vì [reason — e.g., nhiều feature khác phụ thuộc]."
 
-→ User picks feature → Phase 2 (Blueprint + UI Design)
+→ User picks feature → Proceed to Phase 2 (Blueprint) for that feature
 → User wants changes → Adjust architecture
 ```
 
 ---
 
-*Phase 1: Architecture — Design before you build, UI before logic*
+*Phase 1: Architecture — Design before you build*

package/skills/smali-to-kotlin/phase-2-blueprint.md

@@ -0,0 +1,228 @@
+# 📐 Phase 2: Blueprint (Block View — per feature)
+
+> **Zoom Level:** 2 — Feature Detail
+> **Goal:** Design contracts, interfaces, and state for ONE specific feature.
+> **Input:** Architecture Blueprint (Phase 1) + user's chosen feature.
+> **Output:** Feature Blueprint with code signatures. **NO implementation bodies yet.**
+
+---
+
+## ⛔ OUTPUT RULE
+
+```
+✅ ALLOWED: Interface/protocol signatures, data class definitions, sealed classes
+✅ ALLOWED: Retrofit interface with @GET/@POST annotations (no body)
+✅ ALLOWED: UiState sealed class, Event sealed class
+❌ BLOCKED: Function body implementations (use TODO() or // ... )
+❌ BLOCKED: Full ViewModel logic, full Composable implementations
+⚠️ EXCEPTION: Simple data class fields are OK (they ARE the contract)
+```
+
+---
+
+## 📋 Sub-steps (per feature)
+
+### 2.1: Deep Smali Reading
+
+Read the Smali/Java files specifically for the chosen feature.
+
+**What to extract:**
+- Class hierarchy (extends, implements)
+- Field declarations → model properties
+- Method signatures → API contracts
+- String constants → URLs, keys, messages
+- Control flow → business rules (document, don't code)
+
+**Smali Reading Quick Ref:**
+```
+.field → class fields (properties)
+.method → method start
+.end method → method end
+invoke-virtual → instance method call
+invoke-static → static method call
+const-string → string literal
+new-instance → object creation
+if-eqz/if-nez → conditional branches
+```
+
+### 2.2: Domain Model Contracts
+
+Define data classes with exact field mapping:
+
+```kotlin
+// Domain model
+data class User(
+    val id: String,
+    val fullName: String,
+    val email: String,
+    val avatarUrl: String?,
+    val isVerified: Boolean
+)
+
+// DTO (from API)
+@Serializable
+data class UserDto(
+    @SerialName("user_id") val userId: String,
+    @SerialName("full_name") val fullName: String,
+    @SerialName("email") val email: String,
+    @SerialName("avatar_url") val avatarUrl: String?,
+    @SerialName("is_verified") val isVerified: Boolean
+)
+```
+
+### 2.3: Repository Contract
+
+Define interfaces (NO implementation):
+
+```kotlin
+interface AuthRepository {
+    suspend fun login(email: String, password: String): Result<User>
+    suspend fun register(name: String, email: String, password: String): Result<User>
+    suspend fun logout()
+    fun isLoggedIn(): Flow<Boolean>
+    fun getCurrentUser(): Flow<User?>
+}
+```
+
+### 2.4: API Contract
+
+Define Retrofit interface:
+
+```kotlin
+interface AuthApi {
+    @POST("auth/login")
+    suspend fun login(@Body request: LoginRequest): LoginResponse
+
+    @POST("auth/register")
+    suspend fun register(@Body request: RegisterRequest): RegisterResponse
+
+    @GET("auth/me")
+    suspend fun getCurrentUser(@Header("Authorization") token: String): UserDto
+}
+```
+
+### 2.5: UseCase Signatures
+
+```kotlin
+class LoginUseCase(private val authRepo: AuthRepository) {
+    suspend operator fun invoke(email: String, password: String): Result<User>
+    // Implementation: TODO()
+}
+```
+
+### 2.6: UI State Design
+
+This is CRITICAL — design UiState + Events BEFORE coding the ViewModel:
+
+```kotlin
+// State
+data class LoginUiState(
+    val email: String = "",
+    val password: String = "",
+    val isLoading: Boolean = false,
+    val error: String? = null,
+    val isPasswordVisible: Boolean = false
+)
+
+// Events (one-time actions)
+sealed interface LoginEvent {
+    data class NavigateToHome(val user: User) : LoginEvent
+    data class ShowSnackbar(val message: String) : LoginEvent
+}
+
+// Actions (user interactions)
+sealed interface LoginAction {
+    data class UpdateEmail(val email: String) : LoginAction
+    data class UpdatePassword(val password: String) : LoginAction
+    data object TogglePasswordVisibility : LoginAction
+    data object Submit : LoginAction
+}
+```
+
+### 2.7: UI Wireframe
+
+Describe the screen layout in structured text (NOT code):
+
+```markdown
+### LoginScreen Wireframe
+┌──────────────────────┐
+│     [App Logo]       │
+│                      │
+│ ┌──────────────────┐ │
+│ │ Email TextField  │ │
+│ └──────────────────┘ │
+│ ┌──────────────────┐ │
+│ │ Password Field 👁│ │
+│ └──────────────────┘ │
+│                      │
+│ [═══ Login Button ══]│
+│                      │
+│   Forgot Password?   │
+│   Don't have account?│
+│      Register        │
+└──────────────────────┘
+
+Behaviors:
+- Email: validate format on focus lost
+- Password: toggle visibility icon
+- Button: disabled when loading, show progress
+- Error: Snackbar at bottom
+- Success: Navigate to HomeScreen
+```
+
+---
+
+## 📊 Output: Feature Blueprint
+
+Present a clean summary:
+
+```markdown
+## 📐 Blueprint: [Feature Name]
+
+### Smali Analysis Summary
+- Files analyzed: [list]
+- Key observations: [patterns, encryption, special logic]
+
+### Contracts
+- Domain Models: [list with field count]
+- Repository Interface: [method signatures]
+- API Interface: [endpoint signatures]
+- UseCases: [list]
+
+### UI Design
+- UiState: [field list]
+- Events: [list]
+- Actions: [list]
+- Wireframe: [see above]
+
+### Dependencies
+- Depends on: [other features/modules]
+- Depended by: [features that need this]
+
+### Estimated Files
+| File | Layer | Type |
+|------|-------|------|
+| User.kt | Domain/Model | Data class |
+| AuthRepository.kt | Domain/Repository | Interface |
+| AuthRepositoryImpl.kt | Data/Repository | Implementation |
+| AuthApi.kt | Data/Remote | Retrofit interface |
+| LoginUseCase.kt | Domain/UseCase | Class |
+| LoginViewModel.kt | Presentation | ViewModel |
+| LoginScreen.kt | Presentation | Composable |
+```
+
+---
+
+## ✅ Gate
+
+```
+"📐 Blueprint cho [Feature] xong. Anh xem contracts có ổn không?
+Khi OK em sẽ bắt đầu implement (Phase 3)."
+
+→ User approves → Proceed to Phase 3 (Implementation) for this feature
+→ User wants changes → Adjust blueprint
+```
+
+---
+
+*Phase 2: Blueprint — Contracts before code*