@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/skills/swiftui/references/uikit-appkit-interop.md

@@ -0,0 +1,218 @@
+<overview>
+SwiftUI wraps UIKit on iOS and AppKit on macOS. Interoperability enables using UIKit/AppKit features not yet available in SwiftUI, and incrementally adopting SwiftUI in existing projects.
+
+**Bridging patterns:**
+- **SwiftUI → UIKit/AppKit**: UIViewRepresentable, NSViewRepresentable, UIViewControllerRepresentable
+- **UIKit/AppKit → SwiftUI**: UIHostingController, NSHostingController/NSHostingView
+- **Coordinator pattern**: Bridge delegates and target-action patterns to SwiftUI
+
+**When to read this:**
+- Wrapping UIKit views not available in SwiftUI
+- Embedding SwiftUI in existing UIKit apps
+- Handling delegate-based APIs
+</overview>
+
+<uiview_representable>
+## UIViewRepresentable
+
+**Basic structure:**
+```swift
+struct CustomTextField: UIViewRepresentable {
+    @Binding var text: String
+
+    func makeUIView(context: Context) -> UITextField {
+        let textField = UITextField()
+        textField.delegate = context.coordinator
+        return textField
+    }
+
+    func updateUIView(_ uiView: UITextField, context: Context) {
+        if uiView.text != text {
+            uiView.text = text
+        }
+    }
+
+    func makeCoordinator() -> Coordinator {
+        Coordinator(self)
+    }
+
+    class Coordinator: NSObject, UITextFieldDelegate {
+        var parent: CustomTextField
+
+        init(_ parent: CustomTextField) {
+            self.parent = parent
+        }
+
+        func textFieldDidChangeSelection(_ textField: UITextField) {
+            parent.text = textField.text ?? ""
+        }
+    }
+}
+```
+
+**Lifecycle:**
+- `makeUIView` - called once when created
+- `updateUIView` - called when SwiftUI state changes
+- `dismantleUIView` - optional cleanup
+</uiview_representable>
+
+<uiviewcontroller_representable>
+## UIViewControllerRepresentable
+
+```swift
+struct ImagePicker: UIViewControllerRepresentable {
+    @Binding var image: UIImage?
+    @Environment(\.dismiss) var dismiss
+
+    func makeUIViewController(context: Context) -> UIImagePickerController {
+        let picker = UIImagePickerController()
+        picker.delegate = context.coordinator
+        return picker
+    }
+
+    func updateUIViewController(_ uiViewController: UIImagePickerController, context: Context) {}
+
+    func makeCoordinator() -> Coordinator {
+        Coordinator(self)
+    }
+
+    class Coordinator: NSObject, UIImagePickerControllerDelegate, UINavigationControllerDelegate {
+        let parent: ImagePicker
+
+        init(_ parent: ImagePicker) {
+            self.parent = parent
+        }
+
+        func imagePickerController(_ picker: UIImagePickerController, didFinishPickingMediaWithInfo info: [UIImagePickerController.InfoKey : Any]) {
+            parent.image = info[.originalImage] as? UIImage
+            parent.dismiss()
+        }
+    }
+}
+```
+</uiviewcontroller_representable>
+
+<nsview_representable>
+## NSViewRepresentable (macOS)
+
+Same pattern as UIViewRepresentable:
+
+```swift
+struct ColorWell: NSViewRepresentable {
+    @Binding var color: NSColor
+
+    func makeNSView(context: Context) -> NSColorWell {
+        let colorWell = NSColorWell()
+        colorWell.target = context.coordinator
+        colorWell.action = #selector(Coordinator.colorDidChange(_:))
+        return colorWell
+    }
+
+    func updateNSView(_ nsView: NSColorWell, context: Context) {
+        nsView.color = color
+    }
+
+    func makeCoordinator() -> Coordinator {
+        Coordinator(self)
+    }
+
+    class Coordinator: NSObject {
+        var parent: ColorWell
+
+        init(_ parent: ColorWell) {
+            self.parent = parent
+        }
+
+        @objc func colorDidChange(_ sender: NSColorWell) {
+            parent.color = sender.color
+        }
+    }
+}
+```
+</nsview_representable>
+
+<hosting_controller>
+## UIHostingController
+
+**Embedding SwiftUI in UIKit:**
+```swift
+class MainViewController: UIViewController {
+    override func viewDidLoad() {
+        super.viewDidLoad()
+
+        let swiftUIView = MySwiftUIView()
+        let hostingController = UIHostingController(rootView: swiftUIView)
+
+        addChild(hostingController)
+        view.addSubview(hostingController.view)
+
+        hostingController.view.translatesAutoresizingMaskIntoConstraints = false
+        NSLayoutConstraint.activate([
+            hostingController.view.topAnchor.constraint(equalTo: view.topAnchor),
+            hostingController.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            hostingController.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+            hostingController.view.bottomAnchor.constraint(equalTo: view.bottomAnchor)
+        ])
+
+        hostingController.didMove(toParent: self)
+    }
+}
+```
+</hosting_controller>
+
+<coordinator_pattern>
+## Coordinator Pattern
+
+**When to use:**
+- Handling delegate callbacks
+- Managing target-action patterns
+- Bridging imperative events to SwiftUI
+
+**Structure:**
+```swift
+func makeCoordinator() -> Coordinator {
+    Coordinator(self)
+}
+
+class Coordinator: NSObject, SomeDelegate {
+    var parent: ParentView
+
+    init(_ parent: ParentView) {
+        self.parent = parent
+    }
+}
+```
+</coordinator_pattern>
+
+<decision_tree>
+## When to Use Interop
+
+**Use UIKit/AppKit when:**
+- SwiftUI lacks the feature
+- Performance critical scenarios
+- Integrating existing code
+
+**Stay with pure SwiftUI when:**
+- SwiftUI has native support
+- Xcode Previews matter
+- Cross-platform code needed
+</decision_tree>
+
+<anti_patterns>
+## What NOT to Do
+
+<anti_pattern name="UIKit by default">
+**Problem:** Using UIViewRepresentable when SwiftUI works
+**Instead:** Check if SwiftUI added the feature
+</anti_pattern>
+
+<anti_pattern name="Skipping Coordinator">
+**Problem:** Handling delegates without Coordinator
+**Instead:** Always use Coordinator for delegate patterns
+</anti_pattern>
+
+<anti_pattern name="Memory leaks in hosting">
+**Problem:** Not managing child view controller properly
+**Instead:** addChild → addSubview → didMove(toParent:)
+</anti_pattern>
+</anti_patterns>

package/src/resources/skills/swiftui/workflows/add-feature.md

@@ -0,0 +1,191 @@
+<required_reading>
+**Read these reference files NOW before starting:**
+1. `../macos-apps/references/cli-workflow.md` - Build, run, test from CLI
+2. `references/architecture.md` - App structure, MVVM patterns
+3. `references/state-management.md` - Property wrappers, @Observable
+</required_reading>
+
+<process>
+## Step 1: Understand Existing Codebase
+
+```bash
+find . -name "*.swift" -type f | head -20
+```
+
+**Identify:**
+- App architecture (MVVM, TCA, etc.)
+- Existing patterns and conventions
+- Navigation approach
+- Dependency injection method
+
+## Step 2: Plan Feature Integration
+
+**Define scope:**
+- What views needed?
+- What state must be managed?
+- Does it need persistence (SwiftData)?
+- Does it need network calls?
+- How does it connect to existing features?
+
+## Step 3: Create Feature Module
+
+Follow existing organization:
+```
+Features/
+  YourFeature/
+    Views/
+      YourFeatureView.swift
+    ViewModels/
+      YourFeatureViewModel.swift
+    Models/
+      YourFeatureModel.swift
+```
+
+## Step 4: Implement View Model
+
+```swift
+@Observable
+final class YourFeatureViewModel {
+    var items: [YourModel] = []
+    var isLoading = false
+    var errorMessage: String?
+
+    private let dataService: DataService
+
+    init(dataService: DataService) {
+        self.dataService = dataService
+    }
+
+    func loadData() async {
+        isLoading = true
+        defer { isLoading = false }
+
+        do {
+            items = try await dataService.fetchItems()
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+}
+```
+
+## Step 5: Implement Views
+
+```swift
+struct YourFeatureView: View {
+    @State private var viewModel: YourFeatureViewModel
+
+    init(viewModel: YourFeatureViewModel) {
+        self.viewModel = viewModel
+    }
+
+    var body: some View {
+        List(viewModel.items) { item in
+            NavigationLink(value: item) {
+                YourItemRow(item: item)
+            }
+        }
+        .navigationTitle("Feature Title")
+        .navigationDestination(for: YourModel.self) { item in
+            YourFeatureDetailView(item: item)
+        }
+        .task {
+            await viewModel.loadData()
+        }
+    }
+}
+```
+
+## Step 6: Wire Up Navigation
+
+**NavigationStack routing:**
+```swift
+NavigationLink(value: NavigationDestination.yourFeature) {
+    Text("Go to Feature")
+}
+
+.navigationDestination(for: NavigationDestination.self) { destination in
+    switch destination {
+    case .yourFeature:
+        YourFeatureView(viewModel: viewModel)
+    }
+}
+```
+
+**Sheet presentation:**
+```swift
+@State private var showingFeature = false
+
+Button("Show") { showingFeature = true }
+.sheet(isPresented: $showingFeature) {
+    NavigationStack { YourFeatureView(viewModel: viewModel) }
+}
+```
+
+## Step 7: Build and Verify
+
+```bash
+# 1. Build
+xcodebuild -scheme AppName build 2>&1 | xcsift
+
+# 2. Run tests
+xcodebuild -scheme AppName test 2>&1 | xcsift
+
+# 3. Launch and monitor
+# macOS:
+open ./build/Build/Products/Debug/AppName.app
+log stream --predicate 'subsystem == "com.yourcompany.appname"' --level debug
+
+# iOS Simulator:
+xcrun simctl boot "iPhone 15 Pro" 2>/dev/null || true
+xcrun simctl install booted ./build/Build/Products/Debug-iphonesimulator/AppName.app
+xcrun simctl launch booted com.yourcompany.appname
+```
+
+Report to user:
+- "Build: ✓"
+- "Tests: X pass, 0 fail"
+- "Feature added. Ready for you to test [navigation path to feature]"
+
+**User verifies:**
+- Navigate to feature from all entry points
+- Test interactions
+- Check loading/error states
+- Verify light and dark mode
+</process>
+
+<anti_patterns>
+## Avoid These Mistakes
+
+**Not following existing patterns:**
+- Creating new navigation when project has established pattern
+- Using different naming conventions
+- Introducing new DI when project has standard
+
+**Overengineering:**
+- Adding abstraction that doesn't exist elsewhere
+- Creating generic solutions for specific problems
+- Breaking single view into dozens of tiny files prematurely
+
+**Tight coupling:**
+- Accessing other features' view models directly
+- Hardcoding dependencies
+- Circular dependencies between features
+
+**Breaking existing functionality:**
+- Modifying shared view models without checking all callers
+- Changing navigation state structure
+- Removing @Environment values other views depend on
+</anti_patterns>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Feature matches existing architecture patterns
+- [ ] Views compose with existing navigation
+- [ ] State management follows project conventions
+- [ ] Dependency injection consistent with existing code
+- [ ] All existing tests pass
+- [ ] No compiler warnings introduced
+- [ ] Error states handled gracefully
+- [ ] Code follows existing naming conventions
+</success_criteria>

package/src/resources/skills/swiftui/workflows/build-new-app.md

@@ -0,0 +1,311 @@
+<required_reading>
+**Read these reference files NOW before starting:**
+1. `../macos-apps/references/project-scaffolding.md` - XcodeGen templates and file structure
+2. `../macos-apps/references/cli-workflow.md` - Build/run/test from CLI
+3. `references/architecture.md` - MVVM patterns and project structure
+4. `references/state-management.md` - Property wrappers
+</required_reading>
+
+<process>
+## Step 1: Clarify Requirements
+
+Ask the user:
+- What does the app do? (core functionality)
+- Which platform? (iOS, macOS, or both)
+- Any specific features needed? (persistence, networking, system integration)
+
+## Step 2: Scaffold Project with XcodeGen
+
+```bash
+# Create directory structure
+mkdir -p AppName/Sources AppName/Tests AppName/Resources
+cd AppName
+
+# Create project.yml (see ../macos-apps/references/project-scaffolding.md for full template)
+cat > project.yml << 'EOF'
+name: AppName
+options:
+  bundleIdPrefix: com.yourcompany
+  deploymentTarget:
+    iOS: "17.0"
+    macOS: "14.0"
+  xcodeVersion: "15.0"
+  createIntermediateGroups: true
+
+targets:
+  AppName:
+    type: application
+    platform: iOS  # or macOS, or [iOS, macOS] for multi-platform
+    sources: [Sources]
+    resources: [Resources]
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: com.yourcompany.appname
+        DEVELOPMENT_TEAM: YOURTEAMID
+        SWIFT_VERSION: "5.9"
+
+  AppNameTests:
+    type: bundle.unit-test
+    platform: iOS
+    sources: [Tests]
+    dependencies:
+      - target: AppName
+
+schemes:
+  AppName:
+    build:
+      targets:
+        AppName: all
+        AppNameTests: [test]
+    test:
+      targets: [AppNameTests]
+EOF
+
+# Generate xcodeproj
+xcodegen generate
+
+# Verify
+xcodebuild -list -project AppName.xcodeproj
+```
+
+## Step 3: Create Source Files
+
+```
+Sources/
+├── AppNameApp.swift      # App entry point
+├── ContentView.swift     # Main view
+├── Models/
+├── ViewModels/
+├── Views/
+│   ├── Screens/
+│   └── Components/
+├── Services/
+└── Info.plist
+```
+
+## Step 4: Configure App Entry Point
+
+```swift
+import SwiftUI
+
+@main
+struct YourAppNameApp: App {
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+```
+
+## Step 5: Create Base Navigation
+
+**Tab-based app:**
+```swift
+struct MainTabView: View {
+    var body: some View {
+        TabView {
+            HomeView()
+                .tabItem { Label("Home", systemImage: "house") }
+            SettingsView()
+                .tabItem { Label("Settings", systemImage: "gear") }
+        }
+    }
+}
+```
+
+**Stack-based navigation:**
+```swift
+struct RootView: View {
+    var body: some View {
+        NavigationStack {
+            HomeView()
+        }
+    }
+}
+```
+
+## Step 6: Implement First View Model
+
+```swift
+import Foundation
+import Observation
+
+@Observable
+final class HomeViewModel {
+    var items: [Item] = []
+    var isLoading = false
+    var errorMessage: String?
+
+    func loadData() async {
+        isLoading = true
+        defer { isLoading = false }
+
+        do {
+            // items = try await service.fetchItems()
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+}
+```
+
+## Step 7: Create Main View
+
+```swift
+struct HomeView: View {
+    @State private var viewModel = HomeViewModel()
+
+    var body: some View {
+        List(viewModel.items) { item in
+            Text(item.name)
+        }
+        .navigationTitle("Home")
+        .overlay {
+            if viewModel.isLoading { ProgressView() }
+        }
+        .task {
+            await viewModel.loadData()
+        }
+    }
+}
+
+#Preview {
+    NavigationStack { HomeView() }
+}
+```
+
+## Step 8: Wire Up Dependencies
+
+```swift
+@Observable
+final class AppDependencies {
+    let apiService: APIService
+
+    static let shared = AppDependencies()
+
+    private init() {
+        self.apiService = APIService()
+    }
+}
+```
+
+Inject in App:
+```swift
+@main
+struct YourAppNameApp: App {
+    @State private var dependencies = AppDependencies.shared
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+                .environment(dependencies)
+        }
+    }
+}
+```
+
+## Step 9: Build and Verify
+
+```bash
+# Build with error parsing
+xcodebuild -scheme AppName -destination 'platform=iOS Simulator,name=iPhone 15 Pro' build 2>&1 | xcsift
+
+# Boot simulator and install
+xcrun simctl boot "iPhone 15 Pro" 2>/dev/null || true
+xcrun simctl install booted ./build/Build/Products/Debug-iphonesimulator/AppName.app
+
+# Launch and stream logs
+xcrun simctl launch booted com.yourcompany.appname
+log stream --predicate 'subsystem == "com.yourcompany.appname"' --level debug
+```
+
+For macOS apps:
+```bash
+xcodebuild -scheme AppName build 2>&1 | xcsift
+open ./build/Build/Products/Debug/AppName.app
+```
+
+Report to user:
+- "Build: ✓"
+- "App installed on simulator, launching now"
+- "Ready for you to check [specific functionality]"
+</process>
+
+<anti_patterns>
+## Avoid These Mistakes
+
+**Using NavigationView:**
+```swift
+// DON'T
+NavigationView { ContentView() }
+
+// DO
+NavigationStack { ContentView() }
+```
+
+**Using ObservableObject for new code:**
+```swift
+// DON'T
+class ViewModel: ObservableObject {
+    @Published var data = []
+}
+
+// DO
+@Observable
+final class ViewModel {
+    var data = []
+}
+```
+
+**Massive views:**
+```swift
+// DON'T
+struct HomeView: View {
+    var body: some View {
+        VStack { /* 300 lines */ }
+    }
+}
+
+// DO
+struct HomeView: View {
+    var body: some View {
+        VStack {
+            HeaderComponent()
+            ContentList()
+            FooterActions()
+        }
+    }
+}
+```
+
+**Missing previews:**
+```swift
+// Always add previews for iteration
+#Preview { HomeView() }
+```
+
+**Business logic in views:**
+```swift
+// Move to view model
+struct ProductView: View {
+    @State private var viewModel = ProductViewModel()
+
+    var body: some View {
+        Button("Buy") { Task { await viewModel.purchase() } }
+    }
+}
+```
+</anti_patterns>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Project builds without errors
+- [ ] Folder structure matches MVVM pattern
+- [ ] Navigation set up with NavigationStack or TabView
+- [ ] At least one @Observable view model exists
+- [ ] Dependencies injected via @Environment
+- [ ] No deprecated APIs (NavigationView, ObservableObject)
+- [ ] SwiftUI previews render correctly
+- [ ] App launches without warnings
+</success_criteria>