Skip to content

Commit 55c6a87

Browse files
chadparkerchadparker
committed
Claude's plan
1 parent 978913e commit 55c6a87

File tree

1 file changed

+202
-0
lines changed

1 file changed

+202
-0
lines changed

‎AS2/docs/XCODE_MONITORING_PLAN.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# AS2 Xcode Monitoring Implementation Plan
2+
3+
Following the proven architecture of CopilotForXcode, this document outlines the phased approach to implementing comprehensive Xcode monitoring capabilities.
4+
5+
## 🏗️ **Overall Architecture**
6+
7+
**Based on CopilotForXcode's successful pattern:**
8+
- **Pure Accessibility API approach** (no AppleScript)
9+
- **Unsandboxed application** for full system access
10+
- **Real-time AX notification streams** for instant updates
11+
- **Incremental implementation** - build up capabilities gradually
12+
13+
---
14+
15+
## 📋 **Implementation Phases**
16+
17+
### **Phase 1: Foundation & Real-time Monitoring** ⭐ *Next*
18+
**Goal**: Remove sandbox, add accessibility foundation, improve Xcode detection
19+
20+
**Tasks**:
21+
1. **Remove App Sandbox**
22+
- Update `AS2.entitlements`: `com.apple.security.app-sandbox = false`
23+
- Test basic functionality still works
24+
25+
2. **Add Accessibility Foundation**
26+
- Import required frameworks (`ApplicationServices`, `Cocoa`)
27+
- Add basic AXUIElement creation for Xcode apps
28+
- Handle accessibility permission requests
29+
30+
3. **Improve Xcode Detection**
31+
- Fix active/background state detection
32+
- Add better real-time app state updates
33+
- Show Xcode version information
34+
35+
4. **Basic AX Health Check**
36+
- Test AXUIElement creation for detected Xcode instances
37+
- Display basic accessibility status in UI
38+
- Handle permission denied gracefully
39+
40+
**Success Criteria**:
41+
- ✅ App runs without sandbox restrictions
42+
- ✅ Detects Xcode instances accurately
43+
- ✅ Shows accessibility permission status
44+
- ✅ Creates AXUIElements for Xcode apps
45+
46+
---
47+
48+
### **Phase 2: Window & File Path Detection**
49+
**Goal**: Monitor Xcode windows and extract file paths
50+
51+
**Tasks**:
52+
1. **Window Monitoring**
53+
- Detect focused Xcode windows
54+
- Identify workspace vs other window types
55+
- Track window changes in real-time
56+
57+
2. **File Path Extraction** (following CopilotForXcode patterns)
58+
- `extractDocumentURL`: Get current file from `windowElement.document`
59+
- `extractWorkspaceURL`: Parse workspace path from window children
60+
- `extractProjectURL`: Derive project root from workspace/document
61+
62+
3. **Real-time Updates**
63+
- AX notification streams for window focus changes
64+
- Update UI when active document changes
65+
- Handle multiple Xcode windows
66+
67+
**Success Criteria**:
68+
- ✅ Shows current active file path
69+
- ✅ Shows workspace path
70+
- ✅ Updates in real-time when switching files
71+
- ✅ Handles multiple Xcode instances
72+
73+
---
74+
75+
### **Phase 3: Advanced Window Analysis**
76+
**Goal**: Deep window inspection and UI element traversal
77+
78+
**Tasks**:
79+
1. **Window Element Hierarchy**
80+
- Navigate AX element tree structure
81+
- Identify editor areas vs other UI elements
82+
- Find source editor elements specifically
83+
84+
2. **Multiple Window Support**
85+
- Track all open Xcode windows per instance
86+
- Handle split editors and multiple tabs
87+
- Project context awareness
88+
89+
3. **Robustness Features**
90+
- Accessibility API malfunction detection
91+
- Auto-recovery when AX elements become stale
92+
- Error handling for permission changes
93+
94+
**Success Criteria**:
95+
- ✅ Identifies source editor elements
96+
- ✅ Handles complex window layouts
97+
- ✅ Robust error recovery
98+
99+
---
100+
101+
### **Phase 4: Editor Content Access**
102+
**Goal**: Read editor content, cursor position, selections
103+
104+
**Tasks**:
105+
1. **Editor Content Reading**
106+
- Get full text content via `kAXValueAttribute`
107+
- Read selected text ranges
108+
- Parse content into lines
109+
110+
2. **Cursor & Selection Tracking**
111+
- Real-time cursor position updates
112+
- Selection range detection
113+
- Convert between different coordinate systems
114+
115+
3. **Performance Optimization**
116+
- Implement content caching (like CopilotForXcode's `Cache` class)
117+
- Efficient line-based range conversions
118+
- Debounced updates
119+
120+
**Success Criteria**:
121+
- ✅ Displays current editor content
122+
- ✅ Shows cursor position and selections
123+
- ✅ Real-time updates without performance issues
124+
125+
---
126+
127+
### **Phase 5: Advanced Features**
128+
**Goal**: Full feature parity with monitoring capabilities
129+
130+
**Tasks**:
131+
1. **Comprehensive State Tracking**
132+
- Completion panel detection
133+
- Line annotations and error markers
134+
- Scroll position tracking
135+
136+
2. **Multi-Workspace Management**
137+
- Track all open workspaces per Xcode instance
138+
- Workspace-specific context
139+
- Tab enumeration and tracking
140+
141+
3. **Integration Ready**
142+
- Clean APIs for external tools
143+
- Event streaming for other components
144+
- Extensible architecture
145+
146+
---
147+
148+
## 🔧 **Technical Implementation Notes**
149+
150+
### **Key CopilotForXcode Patterns to Follow**:
151+
152+
1. **AXUIElement Management**:
153+
```swift
154+
let app = AXUIElementCreateApplication(processIdentifier)
155+
app.setMessagingTimeout(2)
156+
```
157+
158+
2. **Window Identification**:
159+
```swift
160+
window.identifier == "Xcode.WorkspaceWindow"
161+
```
162+
163+
3. **File Path Extraction**:
164+
```swift
165+
let path = windowElement.document // for current file
166+
// Parse children descriptions for workspace path
167+
```
168+
169+
4. **Real-time Updates**:
170+
```swift
171+
AXNotificationStream(
172+
app: runningApplication,
173+
notificationNames: kAXFocusedUIElementChangedNotification,
174+
kAXTitleChangedNotification, ...
175+
)
176+
```
177+
178+
5. **Error Recovery**:
179+
- Global actor isolation (`@XcodeInspectorActor`)
180+
- Malfunction detection and auto-restart
181+
- Graceful degradation when AX fails
182+
183+
### **Required Entitlements**:
184+
```xml
185+
<key>com.apple.security.app-sandbox</key>
186+
<false/>
187+
<!-- No other special entitlements needed for AX access -->
188+
```
189+
190+
### **User Permission Required**:
191+
- **System Preferences > Security & Privacy > Accessibility**
192+
- App must be explicitly granted permission by user
193+
- Handle permission denied gracefully
194+
195+
---
196+
197+
## 🎯 **Current Status**: Phase 1 Preparation
198+
199+
**Completed**: Basic NSWorkspace monitoring
200+
**Next**: Remove sandbox and implement AX foundation
201+
202+
This plan ensures we build robust, maintainable Xcode monitoring following proven patterns while allowing for incremental development and testing.

0 commit comments

Comments
 (0)