@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/skills/swiftui/workflows/debug-swiftui.md

@@ -0,0 +1,192 @@
+<required_reading>
+**Read these reference files NOW before starting:**
+1. `../macos-apps/references/cli-observability.md` - Log streaming, crash analysis, LLDB, memory debugging
+2. `references/testing-debugging.md` - SwiftUI-specific debugging techniques
+3. `references/state-management.md` - State management issues are #1 bug source
+</required_reading>
+
+<process>
+## Step 1: Reproduce the Bug Consistently
+
+**Isolate the issue:**
+- Create minimal reproducible example
+- Remove unrelated views and logic
+- Test in both preview and simulator/device
+
+**Document:**
+- What action triggers it?
+- Every time or intermittent?
+- Which platforms/OS versions?
+
+## Step 2: Identify Bug Category
+
+**State Management (60% of bugs):**
+- View not updating
+- Infinite update loops
+- @State/@Binding incorrect usage
+- Missing @Observable
+
+**Layout Issues:**
+- Views not appearing
+- Wrong positioning
+- ScrollView/List sizing problems
+
+**Navigation Issues:**
+- Stack corruption
+- Sheets not dismissing
+- Deep linking breaking
+
+**Performance Issues:**
+- UI freezing
+- Excessive redraws
+- Memory leaks
+
+## Step 3: Add Observability
+
+**Add _printChanges() to suspect view:**
+```swift
+var body: some View {
+    let _ = Self._printChanges()
+    // rest of view
+}
+```
+This prints exactly which property caused the view to redraw.
+
+**Add logging for runtime visibility:**
+```swift
+import os
+private let logger = Logger(subsystem: Bundle.main.bundleIdentifier!, category: "Debug")
+
+// In your code:
+logger.debug("State changed: \(self.items.count) items")
+```
+
+**Stream logs from CLI:**
+```bash
+# While app is running
+log stream --predicate 'subsystem == "com.yourcompany.appname"' --level debug
+
+# Search historical logs
+log show --predicate 'subsystem == "com.yourcompany.appname"' --last 1h
+```
+
+## Step 4: Check Common Causes
+
+**State red flags:**
+- Mutating @State from outside owning view
+- Using @StateObject when should use @Observable
+- Missing @Bindable for passing bindings
+
+**View identity issues:**
+- Array index as id when order changes
+- Missing .id() when identity should reset
+- Same id for different content
+
+**Environment problems:**
+- Custom @Environment not provided
+- Using deprecated @EnvironmentObject
+
+## Step 5: Apply Fix
+
+**State fix:**
+```swift
+// Wrong: ObservableObject
+class ViewModel: ObservableObject {
+    @Published var count = 0
+}
+
+// Right: @Observable
+@Observable
+class ViewModel {
+    var count = 0
+}
+```
+
+**View identity fix:**
+```swift
+// Wrong: index as id
+ForEach(items.indices, id: \.self) { index in }
+
+// Right: stable id
+ForEach(items) { item in }
+```
+
+**Navigation fix:**
+```swift
+// Wrong: NavigationView
+NavigationView { }
+
+// Right: NavigationStack
+NavigationStack { }
+```
+
+## Step 6: Verify Fix from CLI
+
+```bash
+# 1. Rebuild
+xcodebuild -scheme AppName build 2>&1 | xcsift
+
+# 2. Run tests
+xcodebuild -scheme AppName test 2>&1 | xcsift
+
+# 3. Launch and monitor
+open ./build/Build/Products/Debug/AppName.app
+log stream --predicate 'subsystem == "com.yourcompany.appname"' --level debug
+
+# 4. Check for memory leaks
+leaks AppName
+
+# 5. If crash occurred, check crash logs
+ls ~/Library/Logs/DiagnosticReports/ | grep AppName
+cat ~/Library/Logs/DiagnosticReports/AppName_*.ips | head -100
+```
+
+**For deep debugging, attach LLDB:**
+```bash
+lldb -n AppName
+(lldb) breakpoint set --file ContentView.swift --line 42
+(lldb) continue
+```
+
+Report to user:
+- "Bug no longer reproduces after [specific fix]"
+- "Tests pass: X pass, 0 fail"
+- "No memory leaks detected"
+- "Ready for you to verify the fix"
+</process>
+
+<anti_patterns>
+## Avoid These Mistakes
+
+**Random changes:**
+- Trying property wrappers without understanding
+- Adding .id(UUID()) hoping it fixes things
+- Wrapping in DispatchQueue.main.async as band-aid
+
+**Ignoring root cause:**
+- Hiding warnings instead of fixing
+- Working around instead of fixing architecture
+
+**Skipping _printChanges():**
+- For state bugs, this is the fastest diagnostic
+- Running this FIRST saves hours
+
+**Using deprecated APIs:**
+- Fix bugs in ObservableObject? Migrate to @Observable
+- NavigationView bugs? Switch to NavigationStack
+
+**Mutating state in body:**
+- Never change @State during body computation
+- Move to .task, .onChange, or button actions
+</anti_patterns>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Bug is reproducible (or documented as intermittent)
+- [ ] Root cause identified using _printChanges() or other tool
+- [ ] Fix applied following SwiftUI best practices
+- [ ] Bug no longer occurs
+- [ ] No new bugs introduced
+- [ ] Tested on all target platforms
+- [ ] Console shows no related warnings
+</success_criteria>

package/src/resources/skills/swiftui/workflows/optimize-performance.md

@@ -0,0 +1,197 @@
+<required_reading>
+**Read these reference files NOW before starting:**
+1. `../macos-apps/references/cli-observability.md` - xctrace profiling, leak detection, memory debugging
+2. `references/performance.md` - Profiling, lazy loading, view identity, optimization
+3. `references/layout-system.md` - Layout containers and GeometryReader pitfalls
+</required_reading>
+
+<process>
+## Step 1: Establish Performance Baseline
+
+```bash
+# Build release for accurate profiling
+xcodebuild -scheme AppName -configuration Release build 2>&1 | xcsift
+
+# List available profiling templates
+xcrun xctrace list templates
+
+# Time Profiler - CPU usage baseline
+xcrun xctrace record \
+  --template 'Time Profiler' \
+  --time-limit 30s \
+  --output baseline-cpu.trace \
+  --launch -- ./build/Build/Products/Release/AppName.app/Contents/MacOS/AppName
+
+# SwiftUI template (if available)
+xcrun xctrace record \
+  --template 'SwiftUI' \
+  --time-limit 30s \
+  --output baseline-swiftui.trace \
+  --launch -- ./build/Build/Products/Release/AppName.app/Contents/MacOS/AppName
+
+# Export trace data
+xcrun xctrace export --input baseline-cpu.trace --toc
+```
+
+Document baseline: CPU usage, view update count, frame rate during slow flows.
+
+## Step 2: Profile View Updates
+
+Add to suspect views:
+```swift
+var body: some View {
+    let _ = Self._printChanges()
+    // rest of view
+}
+```
+
+Check console for which properties caused invalidation.
+
+## Step 3: Fix Unnecessary View Recreation
+
+**Stable view identity:**
+```swift
+// Wrong: index as id
+ForEach(items.indices, id: \.self) { }
+
+// Right: stable id
+ForEach(items) { item in
+    ItemRow(item: item).id(item.id)
+}
+```
+
+**Isolate frequently-changing state:**
+```swift
+// Before: entire list recreates
+struct SlowList: View {
+    @State private var items: [Item] = []
+    @State private var count: Int = 0  // Updates often
+
+    var body: some View {
+        List(items) { item in ItemRow(item: item) }
+    }
+}
+
+// After: isolate count to separate view
+struct FastList: View {
+    @State private var items: [Item] = []
+
+    var body: some View {
+        VStack {
+            CountBadge()  // Only this updates
+            List(items) { item in ItemRow(item: item) }
+        }
+    }
+}
+```
+
+## Step 4: Optimize Lists
+
+```swift
+// Use lazy containers
+ScrollView {
+    LazyVStack(spacing: 8) {
+        ForEach(items) { item in
+            ItemRow(item: item)
+        }
+    }
+}
+```
+
+## Step 5: Reduce Layout Passes
+
+```swift
+// Avoid GeometryReader when possible
+// Before:
+GeometryReader { geo in
+    Circle().frame(width: geo.size.width * 0.8)
+}
+
+// After:
+Circle()
+    .frame(maxWidth: .infinity)
+    .aspectRatio(1, contentMode: .fit)
+    .padding(.horizontal, 20)
+```
+
+## Step 6: Use @Observable
+
+```swift
+// Before: ObservableObject invalidates everything
+class OldViewModel: ObservableObject {
+    @Published var name = ""
+    @Published var count = 0
+}
+
+// After: granular updates
+@Observable
+class ViewModel {
+    var name = ""
+    var count = 0
+}
+```
+
+## Step 7: Verify Improvements from CLI
+
+```bash
+# 1. Rebuild release
+xcodebuild -scheme AppName -configuration Release build 2>&1 | xcsift
+
+# 2. Profile again with same settings
+xcrun xctrace record \
+  --template 'Time Profiler' \
+  --time-limit 30s \
+  --output optimized-cpu.trace \
+  --launch -- ./build/Build/Products/Release/AppName.app/Contents/MacOS/AppName
+
+# 3. Check for memory leaks
+leaks AppName
+
+# 4. Run tests to ensure no regressions
+xcodebuild test -scheme AppName 2>&1 | xcsift
+
+# 5. Launch for user verification
+open ./build/Build/Products/Release/AppName.app
+```
+
+Report to user:
+- "CPU usage reduced from X% to Y%"
+- "View body invocations reduced by Z%"
+- "No memory leaks detected"
+- "Tests: all pass, no regressions"
+- "App launched - please verify scrolling feels smooth"
+</process>
+
+<anti_patterns>
+## Avoid These Mistakes
+
+**Optimizing without profiling:**
+- Always measure with Instruments first
+- Let data guide decisions
+
+**Using .equatable() as first resort:**
+- Masks the issue instead of fixing it
+- Can cause stale UI
+
+**Testing only in simulator:**
+- Simulator runs on Mac CPU
+- Always profile on real devices
+
+**Ignoring view identity:**
+- Use explicit id() when needed
+- Ensure stable IDs in ForEach
+
+**Premature view extraction:**
+- Extract when it isolates state observation
+- Not "for performance" by default
+</anti_patterns>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Time Profiler shows reduced CPU usage
+- [ ] 50%+ reduction in unnecessary view body invocations
+- [ ] Scroll performance at 60fps
+- [ ] App feels responsive on oldest supported device
+- [ ] Memory usage stable, no leaks
+- [ ] _printChanges() confirms targeted updates
+</success_criteria>

package/src/resources/skills/swiftui/workflows/ship-app.md

@@ -0,0 +1,203 @@
+<required_reading>
+**Read these reference files NOW before starting:**
+1. `../macos-apps/references/cli-workflow.md` - Build, test, sign, notarize from CLI
+2. `../macos-apps/references/security-code-signing.md` - Code signing and notarization
+3. `references/platform-integration.md` - iOS/macOS specifics, platform requirements
+</required_reading>
+
+<process>
+## Step 1: Run Tests
+
+```bash
+# iOS
+xcodebuild test -scheme AppName -destination 'platform=iOS Simulator,name=iPhone 15 Pro' 2>&1 | xcsift
+
+# macOS
+xcodebuild test -scheme AppName 2>&1 | xcsift
+```
+
+All tests must pass before shipping.
+
+## Step 2: Profile Performance from CLI
+
+```bash
+# Build release for accurate profiling
+xcodebuild -scheme AppName -configuration Release build 2>&1 | xcsift
+
+# Time Profiler
+xcrun xctrace record \
+  --template 'Time Profiler' \
+  --time-limit 30s \
+  --output ship-profile.trace \
+  --launch -- ./build/Build/Products/Release/AppName.app/Contents/MacOS/AppName
+
+# Check for leaks
+leaks AppName
+
+# Memory allocations
+xcrun xctrace record \
+  --template 'Allocations' \
+  --time-limit 30s \
+  --output ship-allocations.trace \
+  --attach $(pgrep AppName)
+```
+
+Report: "No memory leaks. CPU usage acceptable. Ready to ship."
+
+## Step 3: Update Version Numbers
+
+```bash
+# Marketing version
+/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString 1.0.0" "YourApp/Info.plist"
+
+# Build number (must increment each submission)
+/usr/libexec/PlistBuddy -c "Set :CFBundleVersion 1" "YourApp/Info.plist"
+```
+
+## Step 4: Create Privacy Manifest
+
+Create `PrivacyInfo.xcprivacy` with all accessed APIs:
+- NSPrivacyAccessedAPICategoryUserDefaults
+- NSPrivacyAccessedAPICategoryFileTimestamp
+- etc.
+
+Required for iOS 17+ and macOS 14+.
+
+## Step 5: Verify App Icons
+
+All required sizes in Assets.xcassets:
+- 1024x1024 App Store icon (required)
+- All device sizes filled
+
+## Step 6: Configure Code Signing
+
+Set in project.yml (XcodeGen) or verify existing settings:
+```yaml
+settings:
+  base:
+    CODE_SIGN_STYLE: Automatic
+    DEVELOPMENT_TEAM: YOURTEAMID
+    CODE_SIGN_IDENTITY: "Apple Distribution"
+```
+
+Or set via xcodebuild:
+```bash
+xcodebuild -scheme AppName \
+  CODE_SIGN_STYLE=Automatic \
+  DEVELOPMENT_TEAM=YOURTEAMID \
+  archive
+```
+
+## Step 7: Create Archive
+
+```bash
+xcodebuild archive \
+  -scheme YourApp \
+  -configuration Release \
+  -archivePath ./build/YourApp.xcarchive \
+  -destination 'generic/platform=iOS'
+```
+
+## Step 8: Export for App Store
+
+```bash
+xcodebuild -exportArchive \
+  -archivePath ./build/YourApp.xcarchive \
+  -exportPath ./build/Export \
+  -exportOptionsPlist ExportOptions.plist
+```
+
+## Step 9: Create App in App Store Connect
+
+1. Visit appstoreconnect.apple.com
+2. My Apps → + → New App
+3. Fill in name, bundle ID, SKU
+
+## Step 10: Upload Build from CLI
+
+```bash
+# Validate before upload
+xcrun altool --validate-app -f ./build/Export/AppName.ipa -t ios --apiKey YOUR_KEY --apiIssuer YOUR_ISSUER
+
+# Upload to App Store Connect
+xcrun altool --upload-app -f ./build/Export/AppName.ipa -t ios --apiKey YOUR_KEY --apiIssuer YOUR_ISSUER
+
+# For macOS apps, notarize first (see ../macos-apps/references/security-code-signing.md)
+xcrun notarytool submit AppName.zip --apple-id your@email.com --team-id TEAMID --password @keychain:AC_PASSWORD --wait
+xcrun stapler staple AppName.app
+```
+
+Alternative: Use Transporter app if API keys aren't set up.
+
+## Step 11: Complete Metadata
+
+In App Store Connect:
+- Description (4000 char max)
+- Keywords (100 char max)
+- Screenshots (at least 1 per device type)
+- Privacy Policy URL
+- Support URL
+
+## Step 12: Configure TestFlight (Optional)
+
+1. Wait for build processing
+2. Add internal testers (up to 100)
+3. For external testing, submit for Beta App Review
+
+## Step 13: Submit for Review
+
+1. Select processed build
+2. Complete App Review Information
+3. Provide demo account if login required
+4. Submit for Review
+
+Review typically completes in 24-48 hours.
+
+## Step 14: Handle Outcome
+
+**If approved:** Release manually or automatically
+
+**If rejected:**
+- Read rejection reason
+- Fix issues
+- Increment build number
+- Re-upload and resubmit
+</process>
+
+<anti_patterns>
+## Avoid These Mistakes
+
+**Testing only in simulator:**
+- Always test on physical devices before submission
+
+**Incomplete privacy manifest:**
+- Document all accessed APIs
+- Use Xcode's Privacy Report
+
+**Same build number:**
+- Must increment CFBundleVersion for each upload
+
+**Debug code in release:**
+- Remove NSLog, test accounts, debug views
+- Use #if DEBUG
+
+**Screenshots of splash screen:**
+- Must show app in actual use
+- Guideline 2.3.3 rejection risk
+
+**Not testing exported build:**
+- Export process applies different signing
+- Apps can crash after export despite working in Xcode
+</anti_patterns>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] All tests pass
+- [ ] Version and build numbers updated
+- [ ] Privacy manifest complete
+- [ ] Archive created successfully
+- [ ] Build uploaded to App Store Connect
+- [ ] Metadata and screenshots complete
+- [ ] App submitted for review
+- [ ] App approved and live on App Store
+</success_criteria>