cntx-ui 2.0.13 → 2.0.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/cntx-ui.js +137 -55
- package/lib/agent-runtime.js +1480 -0
- package/lib/agent-tools.js +368 -0
- package/lib/api-router.js +978 -0
- package/lib/bundle-manager.js +471 -0
- package/lib/configuration-manager.js +725 -0
- package/lib/file-system-manager.js +472 -0
- package/lib/heuristics-manager.js +425 -0
- package/lib/mcp-server.js +1054 -1
- package/lib/semantic-splitter.js +7 -14
- package/lib/simple-vector-store.js +329 -0
- package/lib/websocket-manager.js +470 -0
- package/package.json +10 -3
- package/server.js +662 -1933
- package/templates/activities/README.md +67 -0
- package/templates/activities/activities/create-project-bundles/README.md +83 -0
- package/templates/activities/activities/create-project-bundles/notes.md +102 -0
- package/templates/activities/activities/create-project-bundles/progress.md +63 -0
- package/templates/activities/activities/create-project-bundles/tasks.md +39 -0
- package/templates/activities/activities.json +219 -0
- package/templates/activities/lib/.markdownlint.jsonc +18 -0
- package/templates/activities/lib/create-activity.mdc +63 -0
- package/templates/activities/lib/generate-tasks.mdc +64 -0
- package/templates/activities/lib/process-task-list.mdc +52 -0
- package/templates/agent-config.yaml +78 -0
- package/templates/agent-instructions.md +218 -0
- package/templates/agent-rules/capabilities/activities-system.md +147 -0
- package/templates/agent-rules/capabilities/bundle-system.md +131 -0
- package/templates/agent-rules/capabilities/vector-search.md +135 -0
- package/templates/agent-rules/core/codebase-navigation.md +91 -0
- package/templates/agent-rules/core/performance-hierarchy.md +48 -0
- package/templates/agent-rules/core/response-formatting.md +120 -0
- package/templates/agent-rules/project-specific/architecture.md +145 -0
- package/templates/config.json +76 -0
- package/templates/hidden-files.json +14 -0
- package/web/dist/assets/heuristics-manager-browser-DfonOP5I.js +1 -0
- package/web/dist/assets/index-dF3qg-y_.js +2486 -0
- package/web/dist/assets/index-h5FGSg_P.css +1 -0
- package/web/dist/cntx-ui.svg +18 -0
- package/web/dist/index.html +25 -8
- package/lib/semantic-integration.js +0 -441
- package/web/dist/assets/index-Ci1Q-YrQ.js +0 -611
- package/web/dist/assets/index-IUp4q_fr.css +0 -1
- package/web/dist/vite.svg +0 -21
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Vector Search Capabilities
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
Vector search provides semantic code discovery through embedding-based similarity matching. This is the most efficient method for conceptual code exploration.
|
|
5
|
+
|
|
6
|
+
## When Available
|
|
7
|
+
- Look for vector database endpoints: `/api/vector-db/*`
|
|
8
|
+
- Check database status: `GET /api/vector-db/status`
|
|
9
|
+
- Verify chunk count and model information
|
|
10
|
+
|
|
11
|
+
## Core Capabilities
|
|
12
|
+
|
|
13
|
+
### Semantic Search
|
|
14
|
+
**Endpoint**: `POST /api/vector-db/search`
|
|
15
|
+
|
|
16
|
+
**Use for**:
|
|
17
|
+
- "Find functions that handle user authentication"
|
|
18
|
+
- "Locate error handling patterns"
|
|
19
|
+
- "Discover similar implementations"
|
|
20
|
+
- "Explore feature-related code"
|
|
21
|
+
|
|
22
|
+
**Query Format**:
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"query": "semantic description of what you're looking for",
|
|
26
|
+
"limit": 5,
|
|
27
|
+
"minSimilarity": 0.2
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**Best Practices**:
|
|
32
|
+
- Use 3-5 descriptive words: "user authentication login session"
|
|
33
|
+
- Be conceptual, not literal: "form validation" not "validateForm function"
|
|
34
|
+
- Lower similarity thresholds (0.1-0.2) for broader discovery
|
|
35
|
+
- Higher limits (5-10) for comprehensive exploration
|
|
36
|
+
|
|
37
|
+
### Type-Based Search
|
|
38
|
+
**Endpoint**: `POST /api/vector-db/search-by-type`
|
|
39
|
+
|
|
40
|
+
**Use for**:
|
|
41
|
+
- Finding all React components: `{"type": "react_component"}`
|
|
42
|
+
- Locating API handlers: `{"type": "api_integration"}`
|
|
43
|
+
- Discovering utility functions: `{"type": "utility"}`
|
|
44
|
+
|
|
45
|
+
### Domain-Based Search
|
|
46
|
+
**Endpoint**: `POST /api/vector-db/search-by-domain`
|
|
47
|
+
|
|
48
|
+
**Use for**:
|
|
49
|
+
- Business domain exploration: `{"domain": "authentication"}`
|
|
50
|
+
- Technical domain focus: `{"domain": "user-interface"}`
|
|
51
|
+
- Architectural layer discovery: `{"domain": "api"}`
|
|
52
|
+
|
|
53
|
+
## Response Interpretation
|
|
54
|
+
|
|
55
|
+
### Result Structure
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"results": [
|
|
59
|
+
{
|
|
60
|
+
"id": "functionName",
|
|
61
|
+
"similarity": 0.85,
|
|
62
|
+
"metadata": {
|
|
63
|
+
"content": "actual code",
|
|
64
|
+
"semanticType": "react_component",
|
|
65
|
+
"businessDomain": ["authentication"],
|
|
66
|
+
"technicalPatterns": ["hooks", "async_operations"],
|
|
67
|
+
"purpose": "User login form",
|
|
68
|
+
"files": ["src/auth/LoginForm.tsx"],
|
|
69
|
+
"complexity": {"score": 5, "level": "medium"}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
]
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Similarity Scores
|
|
77
|
+
- **0.8+**: Highly relevant, direct match
|
|
78
|
+
- **0.6-0.8**: Good relevance, related functionality
|
|
79
|
+
- **0.4-0.6**: Potentially relevant, worth investigating
|
|
80
|
+
- **0.2-0.4**: Loosely related, may provide context
|
|
81
|
+
- **<0.2**: Probably not relevant
|
|
82
|
+
|
|
83
|
+
### Metadata Usage
|
|
84
|
+
- **semanticType**: Code classification (component, function, etc.)
|
|
85
|
+
- **businessDomain**: Functional area (auth, ui, api, etc.)
|
|
86
|
+
- **technicalPatterns**: Implementation patterns (async, hooks, etc.)
|
|
87
|
+
- **purpose**: Human-readable function description
|
|
88
|
+
- **complexity**: Cognitive complexity metrics
|
|
89
|
+
|
|
90
|
+
## Query Optimization Strategies
|
|
91
|
+
|
|
92
|
+
### Progressive Refinement
|
|
93
|
+
1. Start broad: "user management"
|
|
94
|
+
2. Refine: "user authentication login"
|
|
95
|
+
3. Specific: "user login form validation"
|
|
96
|
+
|
|
97
|
+
### Multiple Approaches
|
|
98
|
+
- Try different phrasings: "data fetching" vs "API calls" vs "HTTP requests"
|
|
99
|
+
- Use synonyms: "configuration" vs "settings" vs "options"
|
|
100
|
+
- Vary abstraction level: "React hooks" vs "state management" vs "useState"
|
|
101
|
+
|
|
102
|
+
### Fallback Strategies
|
|
103
|
+
1. **Lower similarity**: Try minSimilarity: 0.1 for broader results
|
|
104
|
+
2. **Increase limit**: Get more results to find relevant matches
|
|
105
|
+
3. **Different endpoints**: Try search-by-type or search-by-domain
|
|
106
|
+
4. **Simpler queries**: Use fewer, more basic terms
|
|
107
|
+
|
|
108
|
+
## Performance Characteristics
|
|
109
|
+
|
|
110
|
+
### Speed
|
|
111
|
+
- **Typical response**: 20-50ms
|
|
112
|
+
- **Token efficiency**: ~5k tokens vs 50k+ for file reading
|
|
113
|
+
- **Real-time updates**: Automatically stays current with code changes
|
|
114
|
+
|
|
115
|
+
### Accuracy
|
|
116
|
+
- **Best for**: Conceptual discovery and pattern matching
|
|
117
|
+
- **Less effective for**: Exact string matching, specific error messages
|
|
118
|
+
- **Coverage**: Function-level granularity across entire codebase
|
|
119
|
+
|
|
120
|
+
## Integration Patterns
|
|
121
|
+
|
|
122
|
+
### Vector-First Workflow
|
|
123
|
+
```
|
|
124
|
+
User Query → Semantic Search → [Optional: Type/Domain Refinement] → Traditional Search (if needed)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Hybrid Discovery
|
|
128
|
+
1. **Vector search** for broad discovery
|
|
129
|
+
2. **Bundle system** for structural context
|
|
130
|
+
3. **Direct file access** for specific implementation details
|
|
131
|
+
|
|
132
|
+
### Error Handling
|
|
133
|
+
- **Empty results**: Try broader terms or lower similarity threshold
|
|
134
|
+
- **Server error**: Fall back to bundle system or traditional search
|
|
135
|
+
- **Offline**: Use available cached information and traditional methods
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Codebase Navigation - Universal Discovery Patterns
|
|
2
|
+
|
|
3
|
+
## Core Navigation Principles
|
|
4
|
+
|
|
5
|
+
### 1. Progressive Disclosure
|
|
6
|
+
Start high-level, offer to dive deeper:
|
|
7
|
+
- Project overview → Module details → Function specifics
|
|
8
|
+
- Architecture patterns → Implementation details → Code examples
|
|
9
|
+
- Never overwhelm with unnecessary detail
|
|
10
|
+
|
|
11
|
+
### 2. Context-Aware Exploration
|
|
12
|
+
- Understand the user's current focus and intent
|
|
13
|
+
- Provide relevant surrounding context
|
|
14
|
+
- Explain relationships between components
|
|
15
|
+
- Reference architectural boundaries and patterns
|
|
16
|
+
|
|
17
|
+
### 3. Evidence-Based Responses
|
|
18
|
+
Always include:
|
|
19
|
+
- **Specific locations**: `path/to/file.js:23-67`
|
|
20
|
+
- **Confidence indicators**: "Found 3 definitive matches" vs "This appears related"
|
|
21
|
+
- **Source of evidence**: Vector search, AST analysis, or pattern matching
|
|
22
|
+
- **Next step options**: Specific follow-up actions
|
|
23
|
+
|
|
24
|
+
## Operating Modes
|
|
25
|
+
|
|
26
|
+
### Discovery Mode
|
|
27
|
+
*"Tell me about this codebase"*
|
|
28
|
+
- Start with project structure and bundle organization
|
|
29
|
+
- Identify key architectural patterns and frameworks
|
|
30
|
+
- Report complexity metrics and code organization
|
|
31
|
+
- Highlight important entry points and main components
|
|
32
|
+
|
|
33
|
+
### Query Mode
|
|
34
|
+
*"Where is user authentication handled?"*
|
|
35
|
+
- Use semantic search for conceptual discovery
|
|
36
|
+
- Provide specific file paths and line numbers
|
|
37
|
+
- Explain component relationships and data flow
|
|
38
|
+
- Cross-reference with project structure
|
|
39
|
+
|
|
40
|
+
### Investigation Mode
|
|
41
|
+
*"I want to add feature X - what exists already?"*
|
|
42
|
+
- Search for related patterns and implementations
|
|
43
|
+
- Use format: ✅ Existing, ⚠️ Partial, ❌ Missing
|
|
44
|
+
- Identify integration points and extension opportunities
|
|
45
|
+
- Recommend extend vs. create new approaches
|
|
46
|
+
|
|
47
|
+
### Collaboration Mode
|
|
48
|
+
*"Let's discuss the architecture before making changes"*
|
|
49
|
+
- Ask clarifying questions about requirements
|
|
50
|
+
- Suggest alternatives and trade-offs
|
|
51
|
+
- Plan implementation approaches collaboratively
|
|
52
|
+
- Consider project constraints and patterns
|
|
53
|
+
|
|
54
|
+
## Response Structure Template
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
Based on [analysis method] of your codebase:
|
|
58
|
+
|
|
59
|
+
[Direct answer to the question]
|
|
60
|
+
|
|
61
|
+
Key locations:
|
|
62
|
+
1. Primary implementation in `file.js:lines`
|
|
63
|
+
2. Related functionality in `other.js:lines`
|
|
64
|
+
3. Configuration in `config.js:lines`
|
|
65
|
+
|
|
66
|
+
[Brief explanation of relationships and data flow]
|
|
67
|
+
|
|
68
|
+
Next steps:
|
|
69
|
+
- [Specific actionable options]
|
|
70
|
+
- Would you like me to explore [related area]?
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Navigation Efficiency Rules
|
|
74
|
+
|
|
75
|
+
### Bundle-Aware Exploration
|
|
76
|
+
- Start with bundle boundaries to understand project organization
|
|
77
|
+
- Respect existing architectural patterns and conventions
|
|
78
|
+
- Use bundle relationships to scope queries appropriately
|
|
79
|
+
- Reference bundle context in explanations
|
|
80
|
+
|
|
81
|
+
### Semantic Relationships
|
|
82
|
+
- Look for code that works together functionally
|
|
83
|
+
- Identify data flow and dependency patterns
|
|
84
|
+
- Understand abstraction layers and boundaries
|
|
85
|
+
- Map conceptual relationships to actual code structure
|
|
86
|
+
|
|
87
|
+
### User Intent Recognition
|
|
88
|
+
- Classify the type of help needed (learning, debugging, extending)
|
|
89
|
+
- Adjust depth and technical detail appropriately
|
|
90
|
+
- Provide context-sensitive suggestions
|
|
91
|
+
- Offer multiple pathways forward based on user goals
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Performance Hierarchy - Universal Tool Usage Priority
|
|
2
|
+
|
|
3
|
+
## Core Principle
|
|
4
|
+
Always use the fastest, most efficient tool available for each task. Optimize for both response time and token efficiency.
|
|
5
|
+
|
|
6
|
+
## Priority Order
|
|
7
|
+
|
|
8
|
+
### 1. Vector Database (PRIMARY - if available)
|
|
9
|
+
- **Response time**: ~20ms
|
|
10
|
+
- **Token efficiency**: 90% savings vs traditional search
|
|
11
|
+
- **Best for**: Semantic discovery, pattern matching, "find functions that..."
|
|
12
|
+
- **Query format**: Semantic descriptions (3-5 descriptive words)
|
|
13
|
+
- **Example**: "React component state management"
|
|
14
|
+
|
|
15
|
+
### 2. Structured APIs (SECONDARY - if available)
|
|
16
|
+
- **Response time**: ~50ms
|
|
17
|
+
- **Token efficiency**: High (pre-processed data)
|
|
18
|
+
- **Best for**: Project structure, metadata, organized information
|
|
19
|
+
- **Examples**: Bundle systems, AST parsing, configuration APIs
|
|
20
|
+
|
|
21
|
+
### 3. Traditional Search (FALLBACK ONLY)
|
|
22
|
+
- **Response time**: 100ms+
|
|
23
|
+
- **Token efficiency**: Low (raw file content)
|
|
24
|
+
- **Best for**: Exact string matching, specific error messages
|
|
25
|
+
- **Use only when**: Vector search fails or exact keywords needed
|
|
26
|
+
|
|
27
|
+
## Decision Matrix
|
|
28
|
+
|
|
29
|
+
| Task Type | Primary Tool | Secondary | Fallback |
|
|
30
|
+
|-----------|-------------|-----------|----------|
|
|
31
|
+
| Code discovery | Vector search | Bundle API | grep/rg |
|
|
32
|
+
| Pattern matching | Vector search | AST parsing | file scanning |
|
|
33
|
+
| Architecture overview | Bundle API | Vector search | directory listing |
|
|
34
|
+
| Exact string search | grep/rg | Vector search | manual search |
|
|
35
|
+
| Error investigation | Vector search | log parsing | file reading |
|
|
36
|
+
|
|
37
|
+
## Performance Metrics
|
|
38
|
+
- **Vector search**: ~5k tokens per query
|
|
39
|
+
- **Structured APIs**: ~2k tokens per query
|
|
40
|
+
- **File reading**: ~50k+ tokens per file
|
|
41
|
+
- **Directory scanning**: ~20k tokens per scan
|
|
42
|
+
|
|
43
|
+
## Universal Guidelines
|
|
44
|
+
1. **Always try semantic search first** for discovery tasks
|
|
45
|
+
2. **Use structured data when available** for metadata
|
|
46
|
+
3. **Reserve traditional search** for exact matches only
|
|
47
|
+
4. **Combine methods intelligently** (vector discovery → precise lookup)
|
|
48
|
+
5. **Fail gracefully** with clear explanations when tools are unavailable
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Response Formatting - Universal Communication Standards
|
|
2
|
+
|
|
3
|
+
## Core Communication Principles
|
|
4
|
+
|
|
5
|
+
### 1. Clarity and Precision
|
|
6
|
+
- Lead with direct answers to the user's question
|
|
7
|
+
- Use specific, actionable language
|
|
8
|
+
- Avoid unnecessary jargon or complexity
|
|
9
|
+
- Structure information logically
|
|
10
|
+
|
|
11
|
+
### 2. Evidence and Confidence
|
|
12
|
+
- Always cite specific sources and locations
|
|
13
|
+
- Indicate confidence levels in findings
|
|
14
|
+
- Distinguish between definitive facts and reasonable inferences
|
|
15
|
+
- Acknowledge limitations and uncertainty when appropriate
|
|
16
|
+
|
|
17
|
+
### 3. Actionable Guidance
|
|
18
|
+
- Provide clear next steps or options
|
|
19
|
+
- Offer specific follow-up questions or actions
|
|
20
|
+
- Help users make informed decisions
|
|
21
|
+
- Enable users to take immediate action
|
|
22
|
+
|
|
23
|
+
## Response Structure Standards
|
|
24
|
+
|
|
25
|
+
### Standard Response Template
|
|
26
|
+
```markdown
|
|
27
|
+
## [Direct Answer]
|
|
28
|
+
|
|
29
|
+
Based on [analysis method]:
|
|
30
|
+
|
|
31
|
+
### Key Findings:
|
|
32
|
+
1. **Primary location**: `path/file.js:lines` - [brief description]
|
|
33
|
+
2. **Related code**: `path/other.js:lines` - [relationship]
|
|
34
|
+
3. **Configuration**: `path/config.js:lines` - [purpose]
|
|
35
|
+
|
|
36
|
+
### How it works:
|
|
37
|
+
[Brief explanation of relationships and data flow]
|
|
38
|
+
|
|
39
|
+
### Next steps:
|
|
40
|
+
- [ ] [Specific actionable option 1]
|
|
41
|
+
- [ ] [Specific actionable option 2]
|
|
42
|
+
- [ ] Would you like me to explore [related area]?
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Confidence Indicators
|
|
46
|
+
|
|
47
|
+
#### High Confidence (90%+)
|
|
48
|
+
- "Found definitive implementation in..."
|
|
49
|
+
- "The code clearly shows..."
|
|
50
|
+
- "Based on direct analysis of..."
|
|
51
|
+
|
|
52
|
+
#### Medium Confidence (60-90%)
|
|
53
|
+
- "Analysis suggests this is handled by..."
|
|
54
|
+
- "Appears to be implemented in..."
|
|
55
|
+
- "Evidence points to..."
|
|
56
|
+
|
|
57
|
+
#### Low Confidence (40-60%)
|
|
58
|
+
- "This might be related to..."
|
|
59
|
+
- "Could potentially be found in..."
|
|
60
|
+
- "Based on naming patterns, likely..."
|
|
61
|
+
|
|
62
|
+
#### Uncertain (<40%)
|
|
63
|
+
- "No clear evidence found for..."
|
|
64
|
+
- "Unable to locate specific implementation..."
|
|
65
|
+
- "Would need additional investigation to..."
|
|
66
|
+
|
|
67
|
+
## Code Reference Standards
|
|
68
|
+
|
|
69
|
+
### File References
|
|
70
|
+
- Always use relative paths from project root
|
|
71
|
+
- Include line numbers when specific: `src/utils.js:45-67`
|
|
72
|
+
- Use descriptive anchor text: `user authentication logic in auth.js:120`
|
|
73
|
+
|
|
74
|
+
### Code Snippets
|
|
75
|
+
- Include only relevant portions
|
|
76
|
+
- Add context comments when helpful
|
|
77
|
+
- Use syntax highlighting when possible
|
|
78
|
+
- Keep snippets focused and readable
|
|
79
|
+
|
|
80
|
+
### Evidence Attribution
|
|
81
|
+
- Cite the analysis method used: "Vector search found...", "AST analysis shows..."
|
|
82
|
+
- Reference confidence scores when available: "85% similarity match"
|
|
83
|
+
- Distinguish between different types of evidence
|
|
84
|
+
|
|
85
|
+
## Formatting Guidelines
|
|
86
|
+
|
|
87
|
+
### Information Hierarchy
|
|
88
|
+
1. **Direct answer** (what the user asked for)
|
|
89
|
+
2. **Evidence** (where/how you found it)
|
|
90
|
+
3. **Context** (how it fits together)
|
|
91
|
+
4. **Actions** (what to do next)
|
|
92
|
+
|
|
93
|
+
### Visual Organization
|
|
94
|
+
- Use headers and bullet points for scanability
|
|
95
|
+
- Employ consistent formatting patterns
|
|
96
|
+
- Group related information together
|
|
97
|
+
- Use whitespace effectively for readability
|
|
98
|
+
|
|
99
|
+
### Technical Precision
|
|
100
|
+
- Use exact function/variable names
|
|
101
|
+
- Reference specific frameworks and patterns correctly
|
|
102
|
+
- Include relevant technical details without overwhelming
|
|
103
|
+
- Provide accurate line numbers and file paths
|
|
104
|
+
|
|
105
|
+
## Error Communication
|
|
106
|
+
|
|
107
|
+
### When Tools Fail
|
|
108
|
+
- Clearly state what was attempted: "Vector search returned no results for..."
|
|
109
|
+
- Explain the fallback approach: "Using directory structure analysis instead..."
|
|
110
|
+
- Set appropriate expectations: "Limited to file-based pattern matching..."
|
|
111
|
+
|
|
112
|
+
### When Information is Incomplete
|
|
113
|
+
- Acknowledge gaps honestly: "Partial implementation found..."
|
|
114
|
+
- Suggest investigation approaches: "You may want to check..."
|
|
115
|
+
- Offer alternative perspectives: "Another approach might be..."
|
|
116
|
+
|
|
117
|
+
### When Uncertain
|
|
118
|
+
- Express uncertainty clearly: "No definitive evidence found..."
|
|
119
|
+
- Suggest validation steps: "You can verify this by..."
|
|
120
|
+
- Provide multiple possibilities: "This could be handled by either X or Y..."
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Project Architecture - cntx-ui Specific
|
|
2
|
+
|
|
3
|
+
## Project Overview
|
|
4
|
+
cntx-ui is a semantic code analysis and bundle management system with integrated vector search capabilities, designed to help agents and developers understand and navigate codebases intelligently.
|
|
5
|
+
|
|
6
|
+
## Technology Stack
|
|
7
|
+
|
|
8
|
+
### Backend
|
|
9
|
+
- **Node.js**: Server runtime and API layer
|
|
10
|
+
- **Express-style routing**: Custom HTTP request handling
|
|
11
|
+
- **File system operations**: Direct fs module usage for file management
|
|
12
|
+
- **Vector embeddings**: @xenova/transformers for local semantic search
|
|
13
|
+
- **WebSocket**: Real-time updates and communication
|
|
14
|
+
|
|
15
|
+
### Frontend
|
|
16
|
+
- **React + TypeScript**: Modern component-based UI
|
|
17
|
+
- **Vite**: Build tool and development server
|
|
18
|
+
- **TanStack Query**: Data fetching and state management
|
|
19
|
+
- **shadcn/ui**: Component library with Radix UI primitives
|
|
20
|
+
- **Tailwind CSS**: Utility-first styling system
|
|
21
|
+
|
|
22
|
+
### Analysis Engine
|
|
23
|
+
- **Semantic splitter**: Function-level code analysis
|
|
24
|
+
- **Tree-sitter**: AST parsing for precise code understanding
|
|
25
|
+
- **Vector store**: Embedding-based similarity search
|
|
26
|
+
- **Heuristics engine**: Configurable code categorization rules
|
|
27
|
+
|
|
28
|
+
## Key Architectural Patterns
|
|
29
|
+
|
|
30
|
+
### Bundle-Driven Organization
|
|
31
|
+
- **Logical groupings**: Files organized by purpose (frontend, backend, ui-components)
|
|
32
|
+
- **Bundle API**: RESTful endpoints for bundle management
|
|
33
|
+
- **Real-time updates**: File watching and automatic regeneration
|
|
34
|
+
- **XML export**: Structured output for external tool consumption
|
|
35
|
+
|
|
36
|
+
### Semantic Analysis Pipeline
|
|
37
|
+
```
|
|
38
|
+
Source Code → Tree-sitter Parsing → Function Extraction →
|
|
39
|
+
Semantic Classification → Vector Embedding → Search Index
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Agent-Centric Design
|
|
43
|
+
- **Vector-first discovery**: Semantic search as primary exploration method
|
|
44
|
+
- **Modular instructions**: Composable agent rules and capabilities
|
|
45
|
+
- **Activity system**: Structured task management for complex work
|
|
46
|
+
- **Progressive disclosure**: Start high-level, drill down as needed
|
|
47
|
+
|
|
48
|
+
## Directory Structure
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
cntx-ui/
|
|
52
|
+
├── lib/ # Core analysis engines
|
|
53
|
+
│ ├── semantic-splitter.js # Function-level code analysis
|
|
54
|
+
│ ├── simple-vector-store.js # Local embedding search
|
|
55
|
+
│ ├── heuristics-manager.js # Configurable code classification
|
|
56
|
+
│ └── mcp-server.js # Model Context Protocol integration
|
|
57
|
+
├── web/ # React frontend application
|
|
58
|
+
│ ├── src/components/ # UI components
|
|
59
|
+
│ ├── src/lib/ # Client-side utilities
|
|
60
|
+
│ └── dist/ # Built static assets
|
|
61
|
+
├── .cntx/ # Configuration and cache
|
|
62
|
+
│ ├── activities/ # Agent task definitions
|
|
63
|
+
│ ├── agent-rules/ # Modular agent instructions
|
|
64
|
+
│ ├── bundles.json # Bundle configuration
|
|
65
|
+
│ └── semantic-cache.json # Analysis cache
|
|
66
|
+
└── server.js # Main HTTP server and API
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Key Components and Responsibilities
|
|
70
|
+
|
|
71
|
+
### Server Layer (`server.js`)
|
|
72
|
+
- **HTTP API**: RESTful endpoints for all functionality
|
|
73
|
+
- **File watching**: Real-time change detection and cache invalidation
|
|
74
|
+
- **Bundle management**: File organization and generation
|
|
75
|
+
- **Vector integration**: Embedding generation and search
|
|
76
|
+
- **Static serving**: Frontend application hosting
|
|
77
|
+
|
|
78
|
+
### Analysis Engine (`lib/`)
|
|
79
|
+
- **Semantic splitter**: Extracts functions with context and metadata
|
|
80
|
+
- **Vector store**: Manages embeddings and similarity search
|
|
81
|
+
- **Heuristics manager**: Applies configurable classification rules
|
|
82
|
+
- **MCP server**: Provides agent-friendly API access
|
|
83
|
+
|
|
84
|
+
### Frontend (`web/src/`)
|
|
85
|
+
- **Bundle interface**: Visual bundle management and exploration
|
|
86
|
+
- **Activities dashboard**: Agent task monitoring and file viewing
|
|
87
|
+
- **Semantic visualization**: Vector search and analysis results
|
|
88
|
+
- **Settings management**: Configuration and preferences
|
|
89
|
+
|
|
90
|
+
## Data Flow Patterns
|
|
91
|
+
|
|
92
|
+
### Code Analysis Flow
|
|
93
|
+
1. **File change detection** → Cache invalidation
|
|
94
|
+
2. **Semantic analysis** → Function extraction + classification
|
|
95
|
+
3. **Vector embedding** → Search index update
|
|
96
|
+
4. **Bundle regeneration** → Updated file groupings
|
|
97
|
+
5. **Client notification** → Real-time UI updates
|
|
98
|
+
|
|
99
|
+
### Agent Discovery Flow
|
|
100
|
+
1. **Vector search** → Semantic code discovery
|
|
101
|
+
2. **Bundle context** → Architectural understanding
|
|
102
|
+
3. **Activity reference** → Task and progress context
|
|
103
|
+
4. **Precise lookup** → Specific implementation details
|
|
104
|
+
|
|
105
|
+
## Performance Characteristics
|
|
106
|
+
|
|
107
|
+
### Analysis Performance
|
|
108
|
+
- **Semantic analysis**: ~2-5 seconds for full codebase
|
|
109
|
+
- **Vector embedding**: ~100ms per code chunk
|
|
110
|
+
- **Search queries**: ~20ms response time
|
|
111
|
+
- **Bundle generation**: ~500ms for large bundles
|
|
112
|
+
|
|
113
|
+
### Caching Strategy
|
|
114
|
+
- **Semantic cache**: 24-hour TTL with change invalidation
|
|
115
|
+
- **Vector index**: In-memory with disk persistence
|
|
116
|
+
- **Bundle cache**: Real-time updates with file watching
|
|
117
|
+
- **Client cache**: React Query with 5-minute TTL
|
|
118
|
+
|
|
119
|
+
## Integration Points
|
|
120
|
+
|
|
121
|
+
### Agent Tool Integration
|
|
122
|
+
- **Vector search API**: Semantic code discovery
|
|
123
|
+
- **Bundle API**: Structural project understanding
|
|
124
|
+
- **Activities API**: Task management and progress tracking
|
|
125
|
+
- **MCP protocol**: Standardized agent communication
|
|
126
|
+
|
|
127
|
+
### External Tool Support
|
|
128
|
+
- **Cursor integration**: .cursorrules file support
|
|
129
|
+
- **GitHub integration**: Repository analysis and understanding
|
|
130
|
+
- **Export formats**: XML bundles for external tool consumption
|
|
131
|
+
- **CLI interface**: Command-line bundle generation
|
|
132
|
+
|
|
133
|
+
## Development Patterns
|
|
134
|
+
|
|
135
|
+
### Configuration-Driven Development
|
|
136
|
+
- **Heuristics config**: JSON-based code classification rules
|
|
137
|
+
- **Bundle patterns**: Glob-based file organization
|
|
138
|
+
- **Agent rules**: Modular instruction composition
|
|
139
|
+
- **Environment config**: Flexible deployment options
|
|
140
|
+
|
|
141
|
+
### Real-Time Architecture
|
|
142
|
+
- **WebSocket communication**: Live updates between server and client
|
|
143
|
+
- **File watching**: Immediate response to code changes
|
|
144
|
+
- **Cache invalidation**: Automatic refresh of stale data
|
|
145
|
+
- **Progressive enhancement**: Graceful degradation when features unavailable
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
{
|
|
2
|
+
"bundles": {
|
|
3
|
+
"core-server": [
|
|
4
|
+
"server.js",
|
|
5
|
+
"lib/configuration-manager.js",
|
|
6
|
+
"lib/api-router.js",
|
|
7
|
+
"lib/websocket-manager.js"
|
|
8
|
+
],
|
|
9
|
+
"bundle-system": [
|
|
10
|
+
"lib/bundle-manager.js",
|
|
11
|
+
"lib/file-system-manager.js",
|
|
12
|
+
"lib/heuristics-manager.js",
|
|
13
|
+
"heuristics-config.json"
|
|
14
|
+
],
|
|
15
|
+
"ai-processing": [
|
|
16
|
+
"lib/semantic-splitter.js",
|
|
17
|
+
"lib/simple-vector-store.js",
|
|
18
|
+
"lib/function-level-chunker.js",
|
|
19
|
+
"lib/treesitter-semantic-chunker.js",
|
|
20
|
+
"lib/agent-runtime.js",
|
|
21
|
+
"lib/agent-tools.js"
|
|
22
|
+
],
|
|
23
|
+
"mcp-integration": [
|
|
24
|
+
"lib/mcp-server.js",
|
|
25
|
+
"lib/mcp-transport.js",
|
|
26
|
+
"mcp-config-example.json"
|
|
27
|
+
],
|
|
28
|
+
"react-components": [
|
|
29
|
+
"web/src/App.tsx",
|
|
30
|
+
"web/src/main.tsx",
|
|
31
|
+
"web/src/components/BundleList.tsx",
|
|
32
|
+
"web/src/components/BundleListNew.tsx",
|
|
33
|
+
"web/src/components/SystemSettings.tsx",
|
|
34
|
+
"web/src/components/ProjectFiles.tsx",
|
|
35
|
+
"web/src/components/FileAnalysis.tsx"
|
|
36
|
+
],
|
|
37
|
+
"bundle-ui": [
|
|
38
|
+
"web/src/components/bundles/**/*.tsx",
|
|
39
|
+
"web/src/components/bundles/**/*.ts"
|
|
40
|
+
],
|
|
41
|
+
"ui-system": [
|
|
42
|
+
"web/src/components/ui/**/*.tsx",
|
|
43
|
+
"web/src/components/theme-provider.tsx",
|
|
44
|
+
"web/src/components/theme-toggle.tsx",
|
|
45
|
+
"web/src/lib/**/*.ts",
|
|
46
|
+
"web/src/hooks/**/*.ts",
|
|
47
|
+
"web/src/utils/**/*.tsx"
|
|
48
|
+
],
|
|
49
|
+
"config": [
|
|
50
|
+
"package.json",
|
|
51
|
+
"web/package.json",
|
|
52
|
+
"web/vite.config.ts",
|
|
53
|
+
"web/tsconfig*.json",
|
|
54
|
+
"web/eslint.config.js",
|
|
55
|
+
"web/components.json",
|
|
56
|
+
"build.sh"
|
|
57
|
+
],
|
|
58
|
+
"testing": [
|
|
59
|
+
"tests/**/*.js",
|
|
60
|
+
"tests/**/*.mjs",
|
|
61
|
+
"debug/**/*.mjs",
|
|
62
|
+
"web/test-query.mjs",
|
|
63
|
+
"web/simple-test.mjs"
|
|
64
|
+
],
|
|
65
|
+
"docs": [
|
|
66
|
+
"README.md",
|
|
67
|
+
"web/README.md",
|
|
68
|
+
"VISION.md",
|
|
69
|
+
"examples/**/*.sh"
|
|
70
|
+
],
|
|
71
|
+
"master": [
|
|
72
|
+
"**/*"
|
|
73
|
+
]
|
|
74
|
+
},
|
|
75
|
+
"editor": "cursor"
|
|
76
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
class u{constructor(e="http://localhost:3333/api/heuristics/config"){this.configUrl=e,this.config=null,this.cache=new Map,this.lastLoaded=null,this.loadPromise=null}async loadConfig(){return this.loadPromise?this.loadPromise:(this.loadPromise=this._loadConfigInternal(),this.loadPromise)}async _loadConfigInternal(){try{const e=await fetch(this.configUrl);if(!e.ok){if(e.status===404){console.warn("Heuristics config not found at API, using fallback"),this.config=this.getFallbackConfig();return}throw new Error(`HTTP ${e.status}: ${e.statusText}`)}const t=await e.json();this.validateConfig(t),this.config=t,this.lastLoaded=Date.now(),this.cache.clear(),console.log("✅ Heuristics configuration loaded successfully")}catch(e){console.error("❌ Failed to load heuristics config:",e.message),console.log("📦 Falling back to hardcoded heuristics"),this.config=this.getFallbackConfig()}finally{this.loadPromise=null}}validateConfig(e){const t=["purposeHeuristics","bundleHeuristics","semanticTypeMapping"];for(const a of t)if(!e[a])throw new Error(`Missing required field: ${a}`);if(!e.purposeHeuristics.patterns||!e.purposeHeuristics.fallback)throw new Error("Invalid purposeHeuristics structure");if(!e.bundleHeuristics.patterns||!e.bundleHeuristics.fallback)throw new Error("Invalid bundleHeuristics structure")}async getConfig(){return this.config||await this.loadConfig(),this.config}async determinePurpose(e){const t=await this.getConfig(),a=e.name.toLowerCase();for(const[s,n]of Object.entries(t.purposeHeuristics.patterns))if(this.evaluateConditions(n.conditions,{func:e,name:a}))return n.purpose;return t.purposeHeuristics.fallback.purpose}async suggestBundlesForFile(e){const t=await this.getConfig(),a=e.toLowerCase(),s=a.split("/"),n=[];for(const[r,c]of Object.entries(t.bundleHeuristics.patterns))if(this.evaluateConditions(c.conditions,{fileName:a,filePath:e,pathParts:s})&&(n.push(c.bundle),c.subPatterns))for(const[i,o]of Object.entries(c.subPatterns))this.evaluateConditions(o.conditions,{fileName:a,filePath:e,pathParts:s})&&n.push(o.bundle);if(n.length===0){const r=t.bundleHeuristics.fallback;r.webFallback&&this.evaluateConditions(r.webFallback.conditions,{fileName:a,filePath:e,pathParts:s})?n.push(r.webFallback.bundle):r.defaultFallback&&n.push(...r.defaultFallback.bundles)}return[...new Set(n)]}async getSemanticTypeMapping(){const e=await this.getConfig(),t={};for(const[a,s]of Object.entries(e.semanticTypeMapping.clusters))for(const n of s.types)t[n]=s.clusterId;return t}evaluateConditions(e,t){return Array.isArray(e)||(e=[e]),this.requiresAndLogic(e)?e.every(s=>{try{return this.evaluateCondition(s,t)}catch(n){return console.warn(`Failed to evaluate condition: ${s}`,n),!1}}):e.some(s=>{try{return this.evaluateCondition(s,t)}catch(n){return console.warn(`Failed to evaluate condition: ${s}`,n),!1}})}requiresAndLogic(e){return!!(e.length===2&&e.some(t=>t.includes("name.startsWith"))&&e.some(t=>t.includes("func.type"))||e.length===2&&e.some(t=>t.includes("pathParts.includes('web')"))&&e.some(t=>t.includes("pathParts.includes('src')")))}evaluateCondition(e,t){const{func:a,name:s,fileName:n,filePath:r,pathParts:c}=t;if(e.includes("func.type ===")){const i=e.match(/func\.type === ['"]([^'"]+)['"]/);if(i&&a)return a.type===i[1]}if(e.includes("name.startsWith(")){const i=e.match(/name\.startsWith\(['"]([^'"]+)['"]\)/);if(i&&s)return s.startsWith(i[1])}if(e.includes("name.includes(")){const i=e.match(/name\.includes\(['"]([^'"]+)['"]\)/);if(i&&s)return s.includes(i[1])}if(e.includes("fileName.includes(")){const i=e.match(/fileName\.includes\(['"]([^'"]+)['"]\)/);if(i&&n)return n.includes(i[1])}if(e.includes("fileName.endsWith(")){const i=e.match(/fileName\.endsWith\(['"]([^'"]+)['"]\)/);if(i&&n)return n.endsWith(i[1])}if(e.includes("pathParts.includes(")){const i=e.match(/pathParts\.includes\(['"]([^'"]+)['"]\)/);if(i&&c)return c.includes(i[1])}return!1}getFallbackConfig(){return{version:"1.0.0",purposeHeuristics:{patterns:{reactComponent:{conditions:["func.type === 'react_component'"],purpose:"React component",confidence:.95},reactHook:{conditions:["name.startsWith('use')","func.type === 'function'"],purpose:"React hook",confidence:.9},apiHandler:{conditions:["name.includes('api')","name.includes('endpoint')"],purpose:"API handler",confidence:.85},dataRetrieval:{conditions:["name.includes('get')","name.includes('fetch')"],purpose:"Data retrieval",confidence:.8},dataCreation:{conditions:["name.includes('create')","name.includes('add')"],purpose:"Data creation",confidence:.8},dataModification:{conditions:["name.includes('update')","name.includes('edit')"],purpose:"Data modification",confidence:.8},dataDeletion:{conditions:["name.includes('delete')","name.includes('remove')"],purpose:"Data deletion",confidence:.8},validation:{conditions:["name.includes('validate')","name.includes('check')"],purpose:"Validation",confidence:.75},dataProcessing:{conditions:["name.includes('parse')","name.includes('format')"],purpose:"Data processing",confidence:.75}},fallback:{purpose:"Utility function",confidence:.5}},bundleHeuristics:{patterns:{frontend:{conditions:["pathParts.includes('web')","pathParts.includes('src')"],bundle:"frontend",confidence:.8,subPatterns:{uiComponents:{conditions:["pathParts.includes('components')"],bundle:"ui-components",confidence:.9}}},server:{conditions:["fileName.includes('server')","fileName.includes('api')","pathParts.includes('bin')"],bundle:"server",confidence:.85},configuration:{conditions:["fileName.includes('config')","fileName.includes('setup')","fileName.endsWith('.json')","fileName.endsWith('.sh')","fileName.includes('package')"],bundle:"config",confidence:.9},documentation:{conditions:["fileName.endsWith('.md')","fileName.includes('doc')","fileName.includes('readme')"],bundle:"docs",confidence:.95}},fallback:{webFallback:{conditions:["pathParts.includes('web')"],bundle:"frontend",confidence:.6},defaultFallback:{bundles:["server","config"],confidence:.4}}},semanticTypeMapping:{clusters:{businessLogic:{types:["business_logic","algorithm"],clusterId:0},dataLayer:{types:["data_processing","database"],clusterId:1},apiLayer:{types:["api_integration","middleware","routing"],clusterId:2},uiLayer:{types:["ui_component","page_component","layout_component","hook"],clusterId:3},utilities:{types:["utility","configuration","function","type_definition"],clusterId:4},testing:{types:["testing","documentation","monitoring"],clusterId:5},infrastructure:{types:["error_handling","performance","security"],clusterId:6},unknown:{types:["unknown"],clusterId:7}}}}}async updateConfig(e){this.validateConfig(e);try{const t=await fetch(this.configUrl,{method:"PUT",headers:{"Content-Type":"application/json"},body:JSON.stringify(e)});if(!t.ok)throw new Error(`HTTP ${t.status}: ${t.statusText}`);return this.config=e,this.cache.clear(),this.lastLoaded=Date.now(),!0}catch(t){throw console.error("Failed to update heuristics config:",t.message),t}}getPerformanceMetrics(){return{totalEvaluations:0,accuracyScore:0,lastUpdated:this.lastLoaded}}}export{u as default};
|