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.
Files changed (44) hide show
  1. package/bin/cntx-ui.js +137 -55
  2. package/lib/agent-runtime.js +1480 -0
  3. package/lib/agent-tools.js +368 -0
  4. package/lib/api-router.js +978 -0
  5. package/lib/bundle-manager.js +471 -0
  6. package/lib/configuration-manager.js +725 -0
  7. package/lib/file-system-manager.js +472 -0
  8. package/lib/heuristics-manager.js +425 -0
  9. package/lib/mcp-server.js +1054 -1
  10. package/lib/semantic-splitter.js +7 -14
  11. package/lib/simple-vector-store.js +329 -0
  12. package/lib/websocket-manager.js +470 -0
  13. package/package.json +10 -3
  14. package/server.js +662 -1933
  15. package/templates/activities/README.md +67 -0
  16. package/templates/activities/activities/create-project-bundles/README.md +83 -0
  17. package/templates/activities/activities/create-project-bundles/notes.md +102 -0
  18. package/templates/activities/activities/create-project-bundles/progress.md +63 -0
  19. package/templates/activities/activities/create-project-bundles/tasks.md +39 -0
  20. package/templates/activities/activities.json +219 -0
  21. package/templates/activities/lib/.markdownlint.jsonc +18 -0
  22. package/templates/activities/lib/create-activity.mdc +63 -0
  23. package/templates/activities/lib/generate-tasks.mdc +64 -0
  24. package/templates/activities/lib/process-task-list.mdc +52 -0
  25. package/templates/agent-config.yaml +78 -0
  26. package/templates/agent-instructions.md +218 -0
  27. package/templates/agent-rules/capabilities/activities-system.md +147 -0
  28. package/templates/agent-rules/capabilities/bundle-system.md +131 -0
  29. package/templates/agent-rules/capabilities/vector-search.md +135 -0
  30. package/templates/agent-rules/core/codebase-navigation.md +91 -0
  31. package/templates/agent-rules/core/performance-hierarchy.md +48 -0
  32. package/templates/agent-rules/core/response-formatting.md +120 -0
  33. package/templates/agent-rules/project-specific/architecture.md +145 -0
  34. package/templates/config.json +76 -0
  35. package/templates/hidden-files.json +14 -0
  36. package/web/dist/assets/heuristics-manager-browser-DfonOP5I.js +1 -0
  37. package/web/dist/assets/index-dF3qg-y_.js +2486 -0
  38. package/web/dist/assets/index-h5FGSg_P.css +1 -0
  39. package/web/dist/cntx-ui.svg +18 -0
  40. package/web/dist/index.html +25 -8
  41. package/lib/semantic-integration.js +0 -441
  42. package/web/dist/assets/index-Ci1Q-YrQ.js +0 -611
  43. package/web/dist/assets/index-IUp4q_fr.css +0 -1
  44. 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,14 @@
1
+ {
2
+ "globalHidden": [],
3
+ "bundleSpecific": {
4
+ "debugging": [],
5
+ "server": [],
6
+ "frontend": [],
7
+ "config": [],
8
+ "activities": [],
9
+ "tests": [],
10
+ "docs": []
11
+ },
12
+ "userIgnorePatterns": [],
13
+ "disabledSystemPatterns": []
14
+ }
@@ -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};