@leejungkiin/awkit 1.0.6 → 1.0.8

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

@@ -0,0 +1,137 @@
+# 🗺️ Phase 0: Discovery (Satellite View) — iOS
+
+> **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: ASCII diagrams, Mermaid, tables, bullet lists, bash scan commands
+❌ BLOCKED: Swift/ObjC code, function signatures, class definitions
+```
+
+---
+
+## 📋 Sub-steps
+
+### 0.1: Confirm Input
+
+```
+🍎 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: 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
+
+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
+
+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
+
+```
+"🗺️ Đâ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 — No code, just understanding*

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

@@ -0,0 +1,168 @@
+# 🏗️ Phase 1: Architecture (District View) — iOS
+
+> **Zoom Level:** 1 — Architecture Design
+> **Goal:** Design the overall architecture BEFORE writing any code.
+> **Input:** Completed App Map from Phase 0.
+> **Output:** Architecture Blueprint (layer maps, feature tables). **NO CODE BODIES.**
+
+---
+
+## ⛔ OUTPUT RULE
+
+```
+✅ ALLOWED: Architecture diagrams, layer maps, feature-to-file mapping tables
+✅ ALLOWED: File paths, module names, dependency lists
+❌ BLOCKED: Function bodies, implementation details, actual Swift code
+⚠️ EXCEPTION: SPM dependency declarations only
+```
+
+---
+
+## 📋 Sub-steps
+
+### 1.1: Layer Design
+
+Design Clean Architecture layers based on App Map:
+
+```
+┌─────────────────────────────────────┐
+│ Presentation                        │
+│ ├── Screens/ ([N] screens)          │
+│ ├── Navigation/ (NavigationStack)   │
+│ ├── Theme/ (AppTheme)             │
+│ └── Components/ (Shared Views)     │
+├─────────────────────────────────────┤
+│ Domain                              │
+│ ├── Models/ ([N] business models)   │
+│ ├── Repositories/ ([N] protocols)  │
+│ └── UseCases/ ([N] use cases)       │
+├─────────────────────────────────────┤
+│ Data                                │
+│ ├── Network/ (APIClient, Endpoints) │
+│ ├── Local/ (SwiftData, Keychain)   │
+│ └── Repositories/ (implementations)│
+├─────────────────────────────────────┤
+│ DI                                  │
+│ └── AppContainer.swift             │
+└─────────────────────────────────────┘
+```
+
+### 1.2: Feature → File Mapping
+
+| 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
+
+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 + Local | SwiftData |
+| Settings | theme, lang, notif | Local only | @AppStorage |
+
+### 1.5: Xcode Project Structure
+
+```
+App/
+├── App.swift                    # @main entry point
+├── AppDelegate.swift            # UIKit lifecycle (if needed)
+├── Info.plist
+├── Assets.xcassets/
+├── DI/
+│   └── AppContainer.swift
+├── Data/
+│   ├── Network/
+│   │   ├── APIClient.swift
+│   │   ├── Endpoints/
+│   │   └── DTOs/
+│   ├── Local/
+│   │   ├── SwiftDataModels/
+│   │   ├── KeychainService.swift
+│   │   └── UserDefaultsKeys.swift
+│   └── Repositories/
+├── Domain/
+│   ├── Models/
+│   ├── Repositories/
+│   └── UseCases/
+├── Presentation/
+│   ├── Navigation/
+│   │   ├── AppNavigation.swift
+│   │   └── Route.swift
+│   ├── Theme/
+│   │   ├── AppTheme.swift
+│   │   └── Components/
+│   └── Screens/
+│       ├── Launch/
+│       ├── Auth/
+│       ├── Home/
+│       └── .../
+├── Utilities/
+│   ├── Extensions/
+│   ├── Crypto/
+│   └── Helpers/
+└── Resources/
+    ├── Localizable.xcstrings
+    └── Fonts/
+```
+
+### 1.6: Build Order
+
+| # | 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 |
+|----------|--------|-----------|
+| 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
+
+Use template from `templates/architecture.md`.
+
+---
+
+## ✅ Gate
+
+```
+"🏗️ 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*

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

@@ -0,0 +1,348 @@
+# 📐 Phase 2: Blueprint + UI Design (Per Feature) — iOS
+
+> **Zoom Level:** 2 — Feature Detail
+> **Goal:** Design contracts AND code UI visual shell for ONE feature.
+> **Input:** Architecture Blueprint (Phase 1) + user's chosen feature.
+> **Output:** Approved contracts + Working SwiftUI shell with mock data.
+
+---
+
+## ⛔ OUTPUT RULE
+
+```
+PART A — Contracts (signatures only):
+  ✅ Protocol definitions, struct/enum types
+  ✅ APIClient endpoint definitions (signature only, no body)
+  ✅ ViewState struct, ViewAction enum
+  ❌ Function body implementations (use fatalError("TODO"))
+
+PART B — UI (visual code):
+  ✅ Full SwiftUI code for screen
+  ✅ Hardcoded mock data (using ViewState from Part A)
+  ✅ Real resources (icons, colors, images extracted in 2.7)
+  ✅ #Preview for ALL states (normal, loading, error, empty)
+  ❌ Real ViewModel connection — use parameter defaults
+  ❌ Real API calls
+  ❌ Business logic
+```
+
+---
+
+## 📋 Sub-steps
+
+### 2.1: Deep Source Reading
+
+Read class-dump headers + Hopper pseudo-code for the chosen feature.
+
+**What to extract:**
+- Class hierarchy (@interface, @protocol)
+- Property declarations → model fields
+- Method signatures → API contracts
+- String constants → URLs, keys
+- Delegate/callback patterns → async contract signatures
+
+**ObjC Header Quick Ref:**
+```objc
+@interface ClassName : SuperClass <Protocol1, Protocol2>
+@property (nonatomic, copy) NSString *name;     // → let name: String
+@property (nonatomic, strong) NSArray *items;    // → let items: [Item]
+@property (nonatomic, assign) BOOL isActive;     // → let isActive: Bool
+@property (nullable, nonatomic, copy) NSString *bio; // → let bio: String?
+- (void)fetchDataWithCompletion:(void (^)(id, NSError *))completion;
+  // → func fetchData() async throws -> Data
+@end
+```
+
+See `objc-reading-guide.md` for comprehensive guide.
+
+### 2.2: Domain Model Contracts
+
+```swift
+// Domain model
+struct User: Identifiable, Sendable {
+    let id: String
+    let fullName: String
+    let email: String
+    let avatarURL: URL?
+    let isVerified: Bool
+}
+
+// DTO (from API)
+struct UserDTO: Codable {
+    let userId: String
+    let fullName: String
+    let email: String
+    let avatarUrl: String?
+    let isVerified: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case userId = "user_id"
+        case fullName = "full_name"
+        case email
+        case avatarUrl = "avatar_url"
+        case isVerified = "is_verified"
+    }
+
+    func toDomain() -> User {
+        User(id: userId, fullName: fullName, email: email,
+             avatarURL: avatarUrl.flatMap(URL.init), isVerified: isVerified)
+    }
+}
+```
+
+### 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
+    func isLoggedIn() -> Bool
+    func currentUser() async -> User?
+}
+```
+
+### 2.4: API Contract
+
+```swift
+enum AuthEndpoint {
+    case login(email: String, password: String)
+    case register(name: String, email: String, password: String)
+    case currentUser
+
+    var path: String { /* ... */ }
+    var method: HTTPMethod { /* ... */ }
+    // Signature only, no URLRequest body yet
+}
+```
+
+### 2.5: UseCase Signatures
+
+```swift
+struct LoginUseCase {
+    private let authRepo: AuthRepository
+
+    func execute(email: String, password: String) async throws -> User {
+        fatalError("TODO: implement in Phase 3")
+    }
+}
+```
+
+### 2.6: UI State Design
+
+```swift
+// State
+struct LoginViewState {
+    var email: String = ""
+    var password: String = ""
+    var isLoading: Bool = false
+    var error: String? = nil
+    var isPasswordVisible: Bool = false
+}
+
+// Actions (user interactions)
+enum LoginAction {
+    case updateEmail(String)
+    case updatePassword(String)
+    case togglePasswordVisibility
+    case submit
+}
+
+// Events (one-time navigation/alerts)
+enum LoginEvent {
+    case navigateToHome
+    case showError(String)
+}
+
+// Mock data for Preview
+extension LoginViewState {
+    static let normal = LoginViewState(email: "user@example.com")
+    static let loading = LoginViewState(isLoading: true)
+    static let error = LoginViewState(error: "Invalid credentials")
+}
+```
+
+### 2.7: Resource Extraction ⭐ (Before UI code!)
+
+> **Why here?** UI code (2.8) needs real assets. If resources come later, UI will be full of placeholders — defeating the purpose of visual parity.
+
+**Process:**
+1. Extract from `Assets.car` (use `acextract` or screen captures)
+2. Extract from IPA bundle: png, pdf, json, fonts
+3. Copy ONLY needed resources to new Xcode project `Assets.xcassets`
+4. Map string tables to `Localizable.xcstrings`
+
+**Output:**
+```markdown
+### 📦 Resources for [Screen]
+- Images: [list from Assets.xcassets]
+- Colors: [list — add to Color extension or asset catalog]
+- Strings: [list — add to Localizable.xcstrings]
+- Fonts: [custom fonts if any]
+✅ All accessible in SwiftUI
+```
+
+### 2.8: UI Implementation — Visual Shell ⭐
+
+> **Goal:** Code the screen with HARDCODED mock data. Pixel-perfect visual parity with original app.
+
+**Rules:**
+```
+✅ MUST DO:
+  - Use ViewState from 2.6 (hardcode sample values as defaults)
+  - Use REAL resources extracted in 2.7
+  - Display ALL visual elements from original app
+  - Match: spacing, font size, colors, icon placement
+  - Code ALL states: normal, loading, error, empty
+  - Create #Preview for each state
+
+❌ MUST NOT:
+  - Connect real ViewModel (use parameter defaults)
+  - Call real APIs
+  - Code business logic
+  - Use DI/injection
+```
+
+**Pattern — Stateless View:**
+```swift
+struct LoginScreenContent: View {
+    var state: LoginViewState = .normal   // Hardcoded default
+    var onAction: (LoginAction) -> Void = { _ in }  // No-op default
+
+    var body: some View {
+        VStack(spacing: 24) {
+            // Logo — real resource from 2.7
+            Image("app_logo")
+                .resizable()
+                .frame(width: 120, height: 120)
+
+            Spacer().frame(height: 24)
+
+            // Email
+            TextField("Email", text: .constant(state.email))
+                .textFieldStyle(.roundedBorder)
+                .keyboardType(.emailAddress)
+                .textContentType(.emailAddress)
+
+            // Password with toggle
+            HStack {
+                if state.isPasswordVisible {
+                    TextField("Password", text: .constant(state.password))
+                } else {
+                    SecureField("Password", text: .constant(state.password))
+                }
+                Button { onAction(.togglePasswordVisibility) } label: {
+                    Image(systemName: state.isPasswordVisible ? "eye.slash" : "eye")
+                        .foregroundColor(.secondary)
+                }
+            }
+            .textFieldStyle(.roundedBorder)
+
+            // Login Button
+            Button { onAction(.submit) } label: {
+                if state.isLoading {
+                    ProgressView()
+                        .tint(.white)
+                } else {
+                    Text("Login")
+                        .fontWeight(.semibold)
+                }
+            }
+            .frame(maxWidth: .infinity, minHeight: 50)
+            .background(Color.accentColor)
+            .foregroundColor(.white)
+            .cornerRadius(12)
+            .disabled(state.isLoading)
+
+            // Error
+            if let error = state.error {
+                Text(error)
+                    .foregroundColor(.red)
+                    .font(.caption)
+            }
+        }
+        .padding(24)
+    }
+}
+
+// ===== PREVIEWS =====
+#Preview("Normal") {
+    LoginScreenContent(state: .normal)
+}
+
+#Preview("Loading") {
+    LoginScreenContent(state: .loading)
+}
+
+#Preview("Error") {
+    LoginScreenContent(state: .error)
+}
+```
+
+### 2.9: Visual Parity Check ⭐
+
+Compare UI shell with original app screenshot:
+
+```markdown
+### 📸 Visual Parity: [Screen Name]
+
+Layout:
+- [ ] Structure matches original (components, sections)
+- [ ] Spacing between elements correct
+- [ ] Alignment matches
+
+Styling:
+- [ ] Colors match (background, text, buttons, header)
+- [ ] Typography matches (font size, weight)
+- [ ] Icons/images correct and positioned
+- [ ] Borders, shadows, rounded corners
+
+States:
+- [ ] Normal state displays correctly
+- [ ] Loading state — progress in right position
+- [ ] Error state — error message shows properly
+- [ ] Empty state — guidance shown
+
+Platform:
+- [ ] iOS conventions followed (safe area, etc.)
+- [ ] Dynamic Type support
+- [ ] Looks good on different iPhone sizes
+```
+
+---
+
+## 📊 Output: Feature Blueprint + UI
+
+Structured document with contracts + screen screenshots.
+
+---
+
+## ✅ Gate (MANDATORY)
+
+```
+"📐 Blueprint + UI cho [Feature] xong:
+
+📝 Contracts:
+  - [N] domain models
+  - [N] repository protocols
+  - [N] use case signatures
+  - [N] API endpoints
+
+🎨 UI:
+  - [Screen] implemented with mock data
+  - Resources: [N] images, [N] strings, [N] colors
+  - Previews: [N] states (normal, loading, error, empty)
+
+📸 Visual Parity: [OK / cần chỉnh X, Y, Z]
+
+Anh xem UI + contracts ổn không?
+→ ✅ Approve → Phase 3 (Logic Build)
+→ 🎨 Adjust UI → fix then re-check
+→ 📝 Adjust contracts → revise blueprint"
+```
+
+> ⚠️ **DO NOT proceed to Phase 3 until user approves BOTH UI and contracts.**
+
+---
+
+*Phase 2: Blueprint + UI Design — See it before you code it*