@leejungkiin/awkit 1.0.5 → 1.0.7

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

@@ -0,0 +1,154 @@
+# 🔍 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.
+
+---
+
+## ⛔ 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)
+```
+
+---
+
+## 📋 Sub-steps
+
+### 0.1: Scan IPA Structure
+
+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]
+```
+
+### 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.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 |
+
+---
+
+## 📊 Output: App Map
+
+Document all findings in structured format (adapt from Android `templates/app-map.md`).
+
+---
+
+## ✅ 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)"
+```
+
+---
+
+*Phase 0: Discovery — Know your target before you build*

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

@@ -0,0 +1,173 @@
+# 🏗️ Phase 1: Architecture (District View) — iOS
+
+> **Zoom Level:** 1 — Architecture Design
+> **Goal:** Design overall architecture with UI-First build order. NO code bodies.
+> **Input:** Completed App Map from Phase 0.
+> **Output:** Architecture Blueprint document.
+
+---
+
+## ⛔ OUTPUT RULE
+
+```
+✅ ALLOWED: Architecture diagrams, layer maps, feature-to-file mapping, API endpoint tables
+✅ ALLOWED: File paths, module names, dependency lists
+⚠️ ALLOWED: Package.swift skeleton (dependencies only)
+❌ BLOCKED: Function bodies, implementation details, actual Swift code
+```
+
+---
+
+## 📋 Sub-steps
+
+### 1.1: Layer Design
+
+```
+┌─────────────────────────────────────┐
+│ Presentation                        │
+│ ├── Screens/ ([N] screens)          │
+│ ├── Navigation/ (NavigationStack)   │
+│ ├── Theme/ (Design system)          │
+│ └── Components/ (Shared views)      │
+├─────────────────────────────────────┤
+│ Domain                              │
+│ ├── Models/ ([N] business models)   │
+│ ├── Repositories/ ([N] protocols)   │
+│ └── UseCases/ ([N] use cases)       │
+├─────────────────────────────────────┤
+│ Data                                │
+│ ├── Network/ ([N] API endpoints)    │
+│ ├── Local/ (SwiftData, Keychain)    │
+│ └── Repositories/ (implementations) │
+├─────────────────────────────────────┤
+│ DI / Utilities                      │
+│ └── Container, extensions, crypto   │
+└─────────────────────────────────────┘
+```
+
+### 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 |
+| ... | ... | ... | ... | ... | ... |
+
+### 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
+```
+
+### 1.4: Data Schema Inventory
+
+| Model | Key Fields | Source | Storage |
+|-------|-----------|--------|---------|
+| User | id, name, email, avatar | API | SwiftData + Memory |
+| Settings | theme, language | Local | UserDefaults |
+
+### 1.5: Project Structure
+
+```
+App/
+├── App.swift                    # @main entry point
+├── AppDelegate.swift            # UIKit lifecycle (for SDK init)
+├── Info.plist
+├── Assets.xcassets/
+├── DI/
+│   └── AppContainer.swift
+├── Data/
+│   ├── Network/
+│   │   ├── APIClient.swift
+│   │   ├── Endpoints/
+│   │   └── DTOs/
+│   ├── Local/
+│   │   ├── SwiftDataModels/
+│   │   ├── KeychainService.swift
+│   │   └── UserDefaultsKeys.swift
+│   └── Repositories/
+├── Domain/
+│   ├── Models/
+│   ├── Repositories/           # Protocols
+│   └── UseCases/
+├── Presentation/
+│   ├── Navigation/
+│   ├── Theme/
+│   ├── Components/
+│   └── Screens/
+│       ├── Launch/
+│       ├── Auth/
+│       ├── Home/
+│       └── [feature]/
+├── Utilities/
+│   ├── Extensions/
+│   ├── Crypto/
+│   └── Helpers/
+└── Resources/
+    ├── Localizable.xcstrings
+    └── Fonts/
+```
+
+### 1.6: Build Order (UI-First) ⭐
+
+> **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
+```
+
+### 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 |
+| ... | ... | ... |
+
+---
+
+## 📊 Output: Architecture Blueprint
+
+Structured document with all sections above.
+
+---
+
+## ✅ 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
+```
+
+---
+
+*Phase 1: Architecture — Design before you build, UI before logic*

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*