@leejungkiin/awkit 1.0.7 → 1.0.9

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

@@ -1,154 +1,137 @@
-# 🔍 Phase 0: Discovery (Satellite View) — iOS
+# 🗺️ Phase 0: Discovery (Satellite View) — iOS
 
-> **Zoom Level:** 0 — Toàn cảnh
-> **Goal:** Understand the app: structure, frameworks, components, screen flow.
-> **Output:** App Map document.
+> **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 Swift code
-❌ BLOCKED: Any implementation decisions (those come in Phase 1)
+✅ ALLOWED: ASCII diagrams, Mermaid, tables, bullet lists, bash scan commands
+❌ BLOCKED: Swift/ObjC code, function signatures, class definitions
 ```
 
 ---
 
 ## 📋 Sub-steps
 
-### 0.1: Scan IPA Structure
+### 0.1: Confirm Input
 
-Verify decrypted IPA output:
 ```
-Payload/App.app/
-├── App                          # Mach-O binary
-├── Info.plist                   # App metadata
-├── Frameworks/                  # Embedded frameworks
-│   ├── SomeSDK.framework/
-│   └── libswiftCore.dylib
-├── Assets.car                   # Compiled asset catalog
-├── Base.lproj/                  # Storyboards / XIBs (compiled)
-├── *.momd                       # Core Data models
-└── [other resources]
+🍎 iOS Reverse Engineering bắt đầu!
+
+Em cần biết:
+1. Decrypted .app bundle ở đâu?
+2. Class-dump headers ở đâu?
+3. Tên app gốc? Bundle ID?
+
+Chưa chuẩn bị?
+→ bagbak -o ~/decrypted/ com.example.app
+→ class-dump -H ~/decrypted/App.app -o ~/headers/
 ```
 
-### 0.2: Framework Scanner
-
-Scan ALL dependencies before any coding:
-
-1. **Scan `Frameworks/` directory:**
-   ```
-   Frameworks/Alamofire.framework     → Alamofire (network)
-   Frameworks/SDWebImage.framework    → SDWebImage (image)
-   Frameworks/Realm.framework         → Realm (database)
-   Frameworks/FBSDKCoreKit.framework  → Facebook SDK
-   ```
-
-2. **Scan class-dump headers for imports:**
-   ```
-   #import <AFNetworking/...>        → AFNetworking
-   #import <Masonry/...>             → Masonry (auto-layout)
-   @import Firebase;                 → Firebase SDK
-   @import GoogleMobileAds;          → AdMob
-   ```
-
-3. **Check Mach-O linked frameworks:**
-   ```bash
-   otool -L Payload/App.app/App | grep -v /System | grep -v /usr/lib
-   ```
-
-4. **Check embedded dylibs:**
-   ```bash
-   find Payload/App.app -name "*.dylib" -o -name "*.framework" | sort
-   ```
-
-5. **Check for CocoaPods / SPM markers:**
-   ```
-   Pods/ directory → was using CocoaPods
-   .package.resolved → was using SPM
-   ```
-
-See `framework-patterns.md` for comprehensive detection patterns.
-
-### 0.3: Info.plist & Entitlements Analysis
-
-Extract from `Info.plist`:
-
-1. Bundle ID (`CFBundleIdentifier`)
-2. Display Name
-3. Min Deployment Target
-4. Permissions (Privacy keys):
-   ```
-   NSCameraUsageDescription          → Camera
-   NSPhotoLibraryUsageDescription    → Photo Library
-   NSLocationWhenInUseUsageDescription → Location
-   NSMicrophoneUsageDescription      → Microphone
-   ```
-5. URL Schemes (deep links)
-6. Capabilities from entitlements:
-   ```
-   com.apple.developer.associated-domains → Universal Links
-   aps-environment → Push Notifications
-   com.apple.developer.in-app-payments → Apple Pay
-   ```
-
-### 0.4: Class Structure Analysis
-
-From class-dump headers:
-
-1. **Entry points:** AppDelegate, SceneDelegate
-2. **Root ViewController:** Tab bar? Navigation?
-3. **Major ViewControllers** → future SwiftUI screens
-4. **Model classes** → domain models
-5. **Network managers** → API client
-6. **Singleton/manager classes** → services to extract
-
-### 0.5: Screen Flow Map
-
-```mermaid
-graph LR
-    Launch --> Login
-    Login --> MainTab
-    MainTab --> Home
-    MainTab --> Search
-    MainTab --> Profile
-    Home --> Detail
-    Profile --> Settings
+### 0.2: Structure Scan
+
+Quét IPA structure để hiểu quy mô app:
+
+```bash
+# Embedded frameworks
+ls [app_bundle]/Frameworks/ 2>/dev/null
+
+# Linked libraries (non-system)
+otool -L [app_bundle]/[AppName] | grep -v /System | grep -v /usr/lib
+
+# Header imports (from class-dump)
+grep -rh "#import <" [headers_dir]/ | sort -u | head -30
+grep -rh "@import " [headers_dir]/ | sort -u
+
+# Count ViewControllers
+grep -rl "UIViewController" [headers_dir]/ | wc -l
+
+# Resource overview
+ls [app_bundle]/*.car [app_bundle]/*.momd [app_bundle]/*.storyboardc 2>/dev/null
+find [app_bundle] -name "*.json" -o -name "*.plist" | grep -v Info.plist | sort
+
+# SDK identifiers in binary
+strings [app_bundle]/[AppName] | grep -i "cocoapods\|carthage\|firebase\|facebook\|google" | head -20
 ```
 
+### 0.3: Framework Detection
+
+Scan for third-party frameworks. Ref: `framework-patterns.md`
+
+**Phân loại thành 5 nhóm:**
+
+| Category | Meaning | Action |
+|----------|---------|--------|
+| ✅ Reuse | Modern, maintained | Add via SPM |
+| 🔄 Replace | Legacy/deprecated | Map to modern Swift |
+| 🍏 Apple | System frameworks | Use SwiftUI equivalents |
+| 📱 Native | C/C++ dylibs | Keep, bridging header |
+| 🏷️ App Code | Original app logic | Rebuild in Swift |
+
+### 0.4: Info.plist Analysis
+
+```bash
+plutil -p [app_bundle]/Info.plist
+codesign -d --entitlements :- [app_bundle]/[AppName] 2>/dev/null
+```
+
+Extract:
+- Bundle ID, Display Name, Min iOS version
+- Privacy permissions (NSCameraUsageDescription, NSLocationWhenInUseUsageDescription, etc.)
+- URL Schemes (deep links)
+- Capabilities from entitlements (push, Apple Pay, Sign In with Apple, etc.)
+- Supported orientations
+
+### 0.5: Screen Map
+
+Analyze class-dump headers for ViewControllers:
+
+```bash
+# Find all ViewControllers
+grep -rl "UIViewController" [headers_dir]/ | sort
+
+# Find tab bar controllers
+grep -rl "UITabBarController" [headers_dir]/
+
+# Find navigation controllers
+grep -rl "UINavigationController" [headers_dir]/
+```
+
+Map VCs → future SwiftUI screens. Draw navigation flow.
+
 ### 0.6: Complexity Estimate
 
-| Area | Rating | Notes |
-|------|--------|-------|
-| Data Layer | ●●●○○ | [N] APIs, [N] Core Data entities |
-| Core Logic | ●●○○○ | [N] crypto utils, [N] formatters |
-| UI Screens | ●●●●○ | [N] screens, [N] complex views |
-| SDK Integration | ●●○○○ | [N] third-party, [N] native dylibs |
+Rate each area 1-5 dots:
+- Data Layer: ●●●○○ (APIs, DB, keychain)
+- Core Logic: ●●○○○ (crypto, formatters, utils)
+- UI Screens: ●●●●○ (screen count, complex layouts)
+- SDK Integration: ●●○○○ (third-party, native libs)
 
 ---
 
 ## 📊 Output: App Map
 
-Document all findings in structured format (adapt from Android `templates/app-map.md`).
+Use template from `templates/app-map.md`. Must include:
+
+1. **Identity** — bundle ID, min iOS, screen count
+2. **Screen Flow** — navigation graph (ASCII or Mermaid)
+3. **Framework Landscape** — categorized dependency list
+4. **Complexity Estimate** — visual dots rating
+5. **Key Observations** — anything notable
 
 ---
 
 ## ✅ Gate
 
 ```
-"🗺️ App Map xong. Anh review:
-- [N] screens detected
-- [N] frameworks found ([N] reuse, [N] replace)
-- [N] native dylibs
-- 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 điều chỉnh không?"
+→ User approves → Proceed to Phase 1 (Architecture)
 ```
 
 ---
 
-*Phase 0: Discovery — Know your target before you build*
+*Phase 0: Discovery — No code, just understanding*

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

@@ -1,19 +1,19 @@
 # 🏗️ Phase 1: Architecture (District View) — iOS
 
 > **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). **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
 ✅ ALLOWED: File paths, module names, dependency lists
-⚠️ ALLOWED: Package.swift skeleton (dependencies only)
 ❌ BLOCKED: Function bodies, implementation details, actual Swift code
+⚠️ EXCEPTION: SPM dependency declarations only
 ```
 
 ---
@@ -22,65 +22,69 @@
 
 ### 1.1: Layer Design
 
+Design Clean Architecture layers based on App Map:
+
 ```
 ┌─────────────────────────────────────┐
 │ Presentation                        │
 │ ├── Screens/ ([N] screens)          │
 │ ├── Navigation/ (NavigationStack)   │
-│ ├── Theme/ (Design system)          │
-│ └── Components/ (Shared views)      │
+│ ├── Theme/ (AppTheme)             │
+│ └── Components/ (Shared Views)     │
 ├─────────────────────────────────────┤
 │ Domain                              │
 │ ├── Models/ ([N] business models)   │
-│ ├── Repositories/ ([N] protocols)   │
+│ ├── Repositories/ ([N] protocols)  │
 │ └── UseCases/ ([N] use cases)       │
 ├─────────────────────────────────────┤
 │ Data                                │
-│ ├── Network/ ([N] API endpoints)    │
-│ ├── Local/ (SwiftData, Keychain)    │
-│ └── Repositories/ (implementations) │
+│ ├── Network/ (APIClient, Endpoints) │
+│ ├── Local/ (SwiftData, Keychain)   │
+│ └── Repositories/ (implementations)│
 ├─────────────────────────────────────┤
-│ DI / Utilities                      │
-│ └── Container, extensions, crypto   │
+│ DI                                  │
+│ └── AppContainer.swift             │
 └─────────────────────────────────────┘
 ```
 
 ### 1.2: Feature → File Mapping
 
-| Feature | Domain Model | Repository Protocol | UseCase | Screen | ViewModel |
-|---------|-------------|-------------------|---------|--------|-----------|
-| Auth | User, Token | AuthRepository | LoginUC | LoginScreen | AuthVM |
-| Home | Feed | HomeRepository | GetFeedUC | HomeScreen | HomeVM |
+| Feature | Domain Model | Repository | UseCase | Screen(s) | ViewModel |
+|---------|-------------|-----------|---------|-----------|-----------|
+| Auth | User, Token | AuthRepo | LoginUC | Login, Register | AuthVM |
+| Home | [Model] | [Repo] | [UC] | Home | HomeVM |
 | ... | ... | ... | ... | ... | ... |
 
 ### 1.3: API Endpoint Inventory
 
-| # | Method | Endpoint | Auth | Request | Response | Notes |
-|---|--------|----------|------|---------|----------|-------|
-| 1 | POST | /auth/login | No | email, pwd | JWT | - |
-| 2 | GET | /users/me | Bearer | - | User | - |
-
-**How to find in headers/disassembly:**
-```objc
-// class-dump output
-- (void)requestWithURL:(NSURL *)url completion:(void (^)(id, NSError *))completion;
-// Look for string constants with "https://" or "api/"
-// Hopper: search for NSURLSession, dataTaskWithRequest
+Extract ALL API endpoints from class-dump headers + disassembly:
+
+| # | Method | Endpoint | Auth | Notes |
+|---|--------|----------|------|-------|
+| 1 | POST | /auth/login | No | JWT response |
+| 2 | GET | /users/me | Bearer | User profile |
+
+**How to find in class-dump/disassembly:**
+```
+Look for: NSString init with "https://" or "http://"
+Look for: properties named baseURL, apiURL, endpoint
+Look for: method names like fetchUser, loginWith, getProfile
+Look for: AFHTTPSessionManager or NSURLSession usage patterns
 ```
 
 ### 1.4: Data Schema Inventory
 
 | Model | Key Fields | Source | Storage |
 |-------|-----------|--------|---------|
-| User | id, name, email, avatar | API | SwiftData + Memory |
-| Settings | theme, language | Local | UserDefaults |
+| User | id, name, email, avatar | API + Local | SwiftData |
+| Settings | theme, lang, notif | Local only | @AppStorage |
 
-### 1.5: Project Structure
+### 1.5: Xcode Project Structure
 
 ```
 App/
 ├── App.swift                    # @main entry point
-├── AppDelegate.swift            # UIKit lifecycle (for SDK init)
+├── AppDelegate.swift            # UIKit lifecycle (if needed)
 ├── Info.plist
 ├── Assets.xcassets/
 ├── DI/
@@ -97,17 +101,20 @@ App/
 │   └── Repositories/
 ├── Domain/
 │   ├── Models/
-│   ├── Repositories/           # Protocols
+│   ├── Repositories/
 │   └── UseCases/
 ├── Presentation/
 │   ├── Navigation/
+│   │   ├── AppNavigation.swift
+│   │   └── Route.swift
 │   ├── Theme/
-│   ├── Components/
+│   │   ├── AppTheme.swift
+│   │   └── Components/
 │   └── Screens/
 │       ├── Launch/
 │       ├── Auth/
 │       ├── Home/
-│       └── [feature]/
+│       └── .../
 ├── Utilities/
 │   ├── Extensions/
 │   ├── Crypto/
@@ -117,57 +124,45 @@ App/
     └── Fonts/
 ```
 
-### 1.6: Build Order (UI-First) ⭐
+### 1.6: Build Order
 
-> **IMPORTANT:** UI-First build order — design and approve UI before coding logic.
-
-```
-Foundation (one-time):
-  1. 🟢 Xcode project setup + Theme/Design System
-  2. 🟢 Navigation structure (NavigationStack, TabView)
-  3. 🟢 DI Container skeleton
-
-Per Feature (repeat for each):
-  4. 📐 Blueprint: Contracts (models, protocols, use cases, state)
-  5. 🎨 UI Shell: Visual implementation + Resource extraction
-  6. 🚦 GATE: User approve UI
-  7. 🔨 Logic: Domain → Data → ViewModel → Wire UI
-  8. 🧪 Test: Integration + Parity
-
-Final (one-time):
-  9. 📦 SDK Integration + Native libs
-  10. ✅ Full Parity Check
-```
+| # | Phase | Scope | Complexity |
+|---|-------|-------|-----------|
+| 1 | 🟢 Setup | Xcode project + SPM deps + Theme | Low |
+| 2 | 🟢 Models | Domain structs | Low |
+| 3 | 🟡 Data | APIClient + SwiftData + Keychain | Medium |
+| 4 | 🟡 Utils | Crypto, formatters (parity test!) | Medium |
+| 5 | 🔴 Feature: [First] | Blueprint → Build | High |
+| 6 | 🔴 Feature: [Second] | Blueprint → Build | High |
+| N | 🔴 Final | Parity check + QA | High |
 
 ### 1.7: Tech Stack Decisions
 
 | Decision | Choice | Rationale |
 |----------|--------|-----------|
-| Image Loading | Kingfisher | Mature, async, cache |
-| State Management | @Observable | iOS 17+ native |
-| Package Manager | SPM | Apple-native, modern |
-| ... | ... | ... |
+| UI | SwiftUI + iOS 17+ | Modern, declarative |
+| State | @Observable | Latest, no Combine boilerplate |
+| Network | URLSession async/await | Apple native, no deps |
+| JSON | Codable | Built-in, type-safe |
+| Local DB | SwiftData | [or Core Data if < iOS 17] |
+| DI | Protocol + init injection | No framework needed |
+| Package Manager | SPM | Standard, no CocoaPods |
 
 ---
 
 ## 📊 Output: Architecture Blueprint
 
-Structured document with all sections above.
+Use template from `templates/architecture.md`.
 
 ---
 
 ## ✅ Gate
 
 ```
-"🏗️ Architecture Blueprint xong.
-Build order: UI-First per feature.
-Anh muốn bắt đầu từ feature nào?
-Em suggest: [Feature X] vì [reason]."
-
-→ User picks feature → Phase 2 (Blueprint + UI Design)
-→ User wants changes → Adjust architecture
+"🏗️ Architecture Blueprint xong. Anh muốn bắt đầu từ feature nào?"
+→ User picks feature → Phase 2 (Blueprint)
 ```
 
 ---
 
-*Phase 1: Architecture — Design before you build, UI before logic*
+*Phase 1: Architecture — Design before you build*

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

@@ -0,0 +1,173 @@
+# 📐 Phase 2: Blueprint (Block View — per feature) — iOS
+
+> **Zoom Level:** 2 — Feature Detail
+> **Goal:** Design contracts 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: Protocol signatures, struct definitions, enum cases
+✅ ALLOWED: Endpoint definitions (path + method, no body)
+✅ ALLOWED: State design (@Observable properties, no logic)
+❌ BLOCKED: Function body implementations
+❌ BLOCKED: Full ViewModel logic, full View implementations
+```
+
+---
+
+## 📋 Sub-steps (per feature)
+
+### 2.1: Deep Header/Disassembly Reading
+
+Read class-dump headers + Hopper pseudo-code for the chosen feature.
+
+**What to extract:**
+- Class hierarchy (@interface ... : NSObject)
+- Properties → model fields
+- Method signatures → API contracts
+- String constants → URLs, keys
+- Delegate/datasource patterns → business rules
+
+**ObjC Header Reading Quick Ref:**
+```objc
+@property (nonatomic, copy) NSString *name;     // → let name: String
+@property (nonatomic, strong) NSArray *items;    // → let items: [Any]
+@property (nonatomic, assign) BOOL isActive;     // → let isActive: Bool
+@property (nonatomic, assign) NSInteger count;   // → let count: Int
+@property (nullable) NSString *bio;              // → let bio: String?
+
+- (void)fetchWithCompletion:(void(^)(id, NSError*))completion;
+// → func fetch() async throws -> T
+
++ (instancetype)sharedInstance;
+// → static let shared = ClassName()
+```
+
+### 2.2: Domain Model Contracts
+
+```swift
+struct User: Codable, Identifiable, Sendable {
+    let id: String
+    let fullName: String
+    let email: String
+    let avatarUrl: String?
+    let isVerified: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case id = "user_id"
+        case fullName = "full_name"
+        case email
+        case avatarUrl = "avatar_url"
+        case isVerified = "is_verified"
+    }
+}
+```
+
+### 2.3: Repository Contract
+
+```swift
+protocol AuthRepository: Sendable {
+    func login(email: String, password: String) async throws -> User
+    func register(name: String, email: String, password: String) async throws -> User
+    func logout() async
+    var isLoggedIn: AsyncStream<Bool> { get }
+    var currentUser: AsyncStream<User?> { get }
+}
+```
+
+### 2.4: API Contract
+
+```swift
+enum AuthEndpoint: Endpoint {
+    case login(email: String, password: String)
+    case register(name: String, email: String, password: String)
+    case currentUser
+    
+    var path: String { /* ... */ }
+    var method: HTTPMethod { /* ... */ }
+}
+```
+
+### 2.5: UseCase Signatures
+
+```swift
+struct LoginUseCase: Sendable {
+    let authRepository: AuthRepository
+    func execute(email: String, password: String) async throws -> User
+    // Implementation: TODO
+}
+```
+
+### 2.6: UI State Design
+
+```swift
+// ViewModel properties (will be @Observable)
+// - email: String
+// - password: String
+// - isLoading: Bool
+// - showError: Bool
+// - errorMessage: String
+// - isPasswordVisible: Bool
+
+// Actions the view can trigger:
+// - updateEmail(String)
+// - updatePassword(String)
+// - togglePasswordVisibility()
+// - login()
+
+// Navigation events:
+// - navigateToHome(User)
+// - showSnackbar(String)
+```
+
+### 2.7: UI Wireframe
+
+```markdown
+### LoginScreen Wireframe
+┌──────────────────────┐
+│     [App Logo]       │
+│                      │
+│ ┌──────────────────┐ │
+│ │ Email TextField  │ │
+│ └──────────────────┘ │
+│ ┌──────────────────┐ │
+│ │ Password Field 👁│ │
+│ └──────────────────┘ │
+│                      │
+│ [═══ Login Button ══]│
+│                      │
+│   Forgot Password?   │
+│      Register        │
+└──────────────────────┘
+
+Behaviors:
+- Email: .textContentType(.emailAddress), .keyboardType(.emailAddress)
+- Password: toggle visibility, .textContentType(.password)
+- Button: .disabled when loading, overlay ProgressView
+- Error: .alert modifier
+- Success: NavigationStack push to Home
+```
+
+---
+
+## 📊 Output: Feature Blueprint
+
+Use template from `templates/blueprint.md`.
+
+---
+
+## ✅ Gate
+
+```
+"📐 Blueprint cho [Feature] xong. Anh xem contracts ổn không?"
+→ OK → Phase 3 (Implementation)
+→ Adjust → Update blueprint
+```
+
+---
+
+*Phase 2: Blueprint — Contracts before code*