@flisk-sh/flisk 0.0.0-stage → 1.3.190

package/ext/ide-components/README.md

@@ -0,0 +1,221 @@
+# Tilt IDE Components
+
+Web-based IDE features integrated into the Flisk Landscape Tilt development environment.
+
+## Overview
+
+The Tilt IDE provides browser-based tools for browsing, viewing, and executing code without leaving the Tilt UI.
+
+| Component | Port | Traefik URL | Direct URL |
+|-----------|------|-------------|------------|
+| **File Browser** | 9765 | http://files.localhost | http://localhost:9765 |
+| **Code Viewer** | 9766 | http://viewer.localhost | http://localhost:9766 |
+| **Config Inspector** | 9767 | http://configs.localhost | http://localhost:9767 |
+| **Code Executor** | 9768 | http://terminal.localhost | http://localhost:9768 |
+
+> **Note:** `code_executor` is not shipped in the npm package or started by `tilt up` (see #826). Its source stays in the repository.
+
+## Quick Start
+
+All components start automatically when you run `tilt up`:
+
+```bash
+# Start Tilt (IDE components auto-start)
+tilt up
+
+# Or start with focus
+tilt up --focus staff
+
+# IDE components are always available regardless of focus mode
+```
+
+Then open in your browser:
+- 📁 **File Browser**: http://files.localhost (or http://localhost:9765)
+- 👁️ **Code Viewer**: http://viewer.localhost (or http://localhost:9766)
+- ⚙️ **Config Inspector**: http://configs.localhost (or http://localhost:9767)
+- 💻 **Terminal**: http://terminal.localhost (or http://localhost:9768)
+
+## Components
+
+### File Browser (Port 9765)
+
+Browse the entire monorepo filesystem from your browser.
+
+**Features:**
+- Directory tree navigation
+- File metadata (size, modified time)
+- File type icons
+- Search across all files
+- Click any file to open in Code Viewer
+
+**Usage:**
+1. Navigate to http://files.localhost
+2. Click directories to navigate deeper
+3. Use breadcrumb to go back up
+4. Click files to view in Code Viewer (new tab)
+5. Use search box to find files by name
+
+### Code Viewer (Port 9766)
+
+View source files with syntax highlighting.
+
+**Features:**
+- Syntax highlighting for TypeScript, Starlark, JSON, YAML, Prisma, and more
+- Line numbers
+- Read-only indicator
+- File size and modification info
+
+**Usage:**
+1. Open directly: http://viewer.localhost?file=services/product/staff/staff-management-backend/src/index.ts
+2. Or click files from File Browser
+3. Supports files up to 1MB
+
+### Config Inspector (Port 9767)
+
+Compare master Tilt configurations (.star files) with their auto-generated outputs.
+
+**Features:**
+- Browse all .star config files organized by category
+- Side-by-side comparison of master vs generated
+- One-click "Regenerate" action (coming soon)
+
+**Usage:**
+1. Navigate to http://configs.localhost
+2. Select a .star file from the sidebar
+3. View master config on left, generated outputs on right
+4. Click "Regenerate" to trigger config regeneration
+
+### Code Executor (Port 9768)
+
+Execute bun commands from the browser.
+
+**Features:**
+- Terminal interface in browser
+- Command history (up/down arrows)
+- Real-time output with color coding
+- Safety restrictions (no rm -rf /)
+- Supports: bun, npm, git, and safe shell commands
+
+**Usage:**
+1. Navigate to http://terminal.localhost
+2. Type commands like `bun test`, `ls -la`, `git status`
+3. Press Enter to execute
+4. Use Up/Down arrows to recall previous commands
+
+## Architecture
+
+Each component is a Python HTTP server:
+
+```
+.tilt-engine/extensions/ide-components/
+├── file_browser/
+│   └── server.py          # Port 9765
+├── code_viewer/
+│   └── server.py          # Port 9766
+├── config_inspector/
+│   └── server.py          # Port 9767
+├── code_executor/
+│   └── server.py          # Port 9768
+└── shared/
+    ├── file_utils.py      # Safe file operations
+    ├── templates/
+    │   └── base.html      # Common HTML template
+    └── static/
+        └── styles.css     # Shared CSS styles
+```
+
+### Key Design Decisions
+
+1. **Python (not Bun/Node)**: Avoids circular dependency - IDE works even if Bun has issues
+2. **Separate servers**: Each component is independent, can restart individually
+3. **Read-only viewer**: Safety first - editing happens in proper IDEs
+4. **localhost only**: Security - not exposed to network
+
+## Safety
+
+### File Access
+- ✅ Only reads within project root
+- ✅ Blocks path traversal attacks (../etc/passwd)
+- ✅ 1MB file size limit
+- ✅ Hidden files excluded from browser
+
+### Command Execution
+- ✅ Only bun, npm, git, and safe shell commands allowed
+- ✅ Blocks: rm -rf /, sudo, su, passwd, etc.
+- ✅ 60-second timeout on commands
+- ✅ Commands run in project directory only
+
+## Troubleshooting
+
+### Port Already in Use
+
+If you see "Address already in use":
+
+```bash
+# Find what's using the port
+lsof -i :9765  # or 9766, 9767, 9768
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Components Not Starting
+
+Check the Tilt logs:
+
+```bash
+# View specific component logs
+tilt logs tilt-file-browser
+tilt logs tilt-code-viewer
+tilt logs tilt-config-inspector
+tilt logs tilt-code-executor
+```
+
+### Python Not Found
+
+Ensure Python 3 is installed:
+
+```bash
+python3 --version
+
+# On macOS (if needed)
+brew install python3
+```
+
+## Future Enhancements
+
+- [ ] Service context actions (View Source, Run Tests) in Tilt UI
+- [ ] Regenerate button that actually triggers `tilt trigger`
+- [ ] Dark/light theme toggle
+- [ ] Keyboard shortcuts (Ctrl+K for search)
+- [ ] File type icons (font-based)
+- [ ] Mobile responsiveness
+- [ ] VS Code extension integration
+
+## Development
+
+To work on IDE components:
+
+```bash
+# Test file browser standalone
+cd .tilt-engine/extensions/ide-components/file_browser
+python3 server.py
+
+# Test code viewer standalone
+cd .tilt-engine/extensions/ide-components/code_viewer
+python3 server.py
+```
+
+Then open http://localhost:9765 (or 9766, etc.) in your browser.
+
+## Integration with Alpha Health Dashboard
+
+The IDE components work alongside the alpha health dashboard:
+
+- **Health Dashboard**: http://localhost:8765/alpha-health-dashboard.html
+- **File Browser**: http://files.localhost
+- **Code Viewer**: http://viewer.localhost
+- **Config Inspector**: http://configs.localhost
+- **Terminal**: http://terminal.localhost
+
+All components run independently and can be used simultaneously.

package/ext/ide-components/code_viewer/server.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Flisk Landscape contributors
+# SPDX-License-Identifier: MIT
+"""
+Tilt IDE Code Viewer
+Serves syntax-highlighted code viewing at http://localhost:9766
+"""
+
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+
+# Add shared modules
+sys.path.insert(0, str(Path(__file__).parent.parent / 'shared'))
+from file_utils import FileUtils, PROJECT_ROOT
+from http_utils import BaseIDEHandler, run_server
+
+PORT = 9766
+
+
+class CodeViewerHandler(BaseIDEHandler):
+    """HTTP request handler for code viewer"""
+    
+    def simple_highlight(self, code: str, language: str) -> str:
+        """Simple syntax highlighting using regex"""
+        # Escape HTML first
+        code = self.escape_html(code)
+        
+        # Keywords (common across languages)
+        keywords = [
+            'import', 'from', 'export', 'default', 'const', 'let', 'var', 'function',
+            'class', 'interface', 'type', 'return', 'if', 'else', 'for', 'while',
+            'switch', 'case', 'break', 'continue', 'try', 'catch', 'finally', 'async',
+            'await', 'new', 'this', 'super', 'extends', 'implements', 'static',
+            'public', 'private', 'protected', 'package', 'def', 'load', 'struct',
+            'struct', 'load', 'if', 'else', 'for', 'in', 'return', 'def', 'True', 'False',
+        ]
+        
+        # Highlight keywords
+        for kw in keywords:
+            pattern = rf'\b({kw})\b'
+            code = re.sub(pattern, r'<span class="syntax-keyword">\1</span>', code)
+        
+        # Strings
+        code = re.sub(r'(".*?")', r'<span class="syntax-string">\1</span>', code)
+        code = re.sub(r"('.*?')", r'<span class="syntax-string">\1</span>', code)
+        code = re.sub(r'(`[\s\S]*?`)', r'<span class="syntax-string">\1</span>', code)
+        
+        # Comments
+        code = re.sub(r'(//.*$)', r'<span class="syntax-comment">\1</span>', code, flags=re.MULTILINE)
+        code = re.sub(r'(#.*$)', r'<span class="syntax-comment">\1</span>', code, flags=re.MULTILINE)
+        
+        # Numbers
+        code = re.sub(r'\b(\d+)\b', r'<span class="syntax-number">\1</span>', code)
+        
+        return code
+    
+    def render_code_with_line_numbers(self, code: str, language: str) -> str:
+        """Render code with line numbers"""
+        lines = code.split('\n')
+        highlighted = self.simple_highlight(code, language)
+        highlighted_lines = highlighted.split('\n')
+        
+        html = ['<table style="width:100%; border-collapse: collapse;">']
+        html.append('<tr>')
+        
+        # Line numbers column
+        html.append('<td class="line-numbers" style="vertical-align: top; padding-right: 1rem; width: 50px;">')
+        for i in range(1, len(lines) + 1):
+            html.append(f'<div>{i}</div>')
+        html.append('</td>')
+        
+        # Code column
+        html.append('<td style="vertical-align: top;">')
+        html.append('<pre style="margin: 0;"><code>')
+        for line in highlighted_lines:
+            html.append(f'<div>{line or "&nbsp;"}</div>')
+        html.append('</code></pre>')
+        html.append('</td>')
+        
+        html.append('</tr>')
+        html.append('</table>')
+        
+        return ''.join(html)
+    
+    def _get_template_path(self) -> Path:
+        """Override to use shared template"""
+        return Path(__file__).parent.parent / 'shared' / 'templates' / 'base.html'
+    
+    def do_GET(self):
+        """Handle GET requests"""
+        import json
+        
+        parsed = urllib.parse.urlparse(self.path)
+        path = parsed.path
+        query = urllib.parse.parse_qs(parsed.query)
+        
+        # Health check
+        if path == '/health':
+            self.handle_health_check('code-viewer')
+            return
+        
+        # Static files
+        if path.startswith('/static/'):
+            static_path = Path(__file__).parent.parent / 'shared' / path[1:]
+            if static_path.exists():
+                with open(static_path, 'r') as f:
+                    content = f.read()
+                self.send_css_response(content)
+            else:
+                self.send_error_response(404, 'Not found')
+            return
+        
+        # View file
+        if path == '/view' or path == '/':
+            file_path = query.get('file', [''])[0]
+            
+            if not file_path:
+                # Show welcome/empty state
+                content = '''
+                    <div class="empty-state">
+                        <div class="empty-state-icon">👁️</div>
+                        <h2>Code Viewer</h2>
+                        <p>Open a file from the <a href="http://localhost:9765">File Browser</a> to view its contents.</p>
+                        <p class="text-muted">Supports TypeScript, JavaScript, Starlark, JSON, YAML, and more.</p>
+                    </div>
+                '''
+                self.send_html_response(self.render_page('Code Viewer', content, icon='👁️'))
+                return
+            
+            # Read file
+            content, error = FileUtils.read_file_safe(file_path)
+            
+            if error:
+                error_content = f'''
+                    <div class="code-container">
+                        <div class="code-header">
+                            <div class="code-header-left">
+                                <span class="file-path">{self.escape_html(file_path)}</span>
+                            </div>
+                        </div>
+                        <div class="code-content">
+                            <div class="empty-state">
+                                <div class="empty-state-icon">⚠️</div>
+                                <p>{self.escape_html(error)}</p>
+                                <p class="text-muted"><a href="http://localhost:9765">← Back to File Browser</a></p>
+                            </div>
+                        </div>
+                    </div>
+                '''
+                self.send_html_response(self.render_page('Error', error_content, icon='⚠️'), 404)
+                return
+            
+            # Get file info
+            resolved = FileUtils.validate_path(file_path)
+            file_info = FileUtils.get_file_info(resolved) if resolved else {'name': file_path, 'size_str': 'Unknown'}
+            
+            # Determine language
+            ext = Path(file_path).suffix.lower()
+            language = FileUtils.get_language_from_ext(ext)
+            
+            # Render code
+            code_html = self.render_code_with_line_numbers(content, language)
+            
+            page_content = f'''
+                <div class="code-container">
+                    <div class="code-header">
+                        <div class="code-header-left">
+                            <span class="file-path">{self.escape_html(file_path)}</span>
+                            <span class="read-only-badge">👁️ READ-ONLY</span>
+                        </div>
+                        <div>
+                            <span class="text-muted">{file_info['size_str']} • {file_info['modified']}</span>
+                        </div>
+                    </div>
+                    <div class="code-content">
+                        {code_html}
+                    </div>
+                </div>
+                <div style="margin-top: 1rem; text-align: center;">
+                    <a href="http://localhost:9765/browse?path={urllib.parse.quote(str(Path(file_path).parent))}" class="text-muted">← Back to directory</a>
+                </div>
+            '''
+            
+            self.send_html_response(self.render_page(f"{file_info['name']}", page_content, icon='👁️'))
+            return
+        
+        # 404
+        self.send_html_response(self.render_page(
+            'Not Found',
+            '<div class="empty-state"><div class="empty-state-icon">❓</div>Page not found</div>',
+            icon='❓'
+        ), 404)
+
+
+def main():
+    """Run the code viewer server"""
+    run_server(
+        CodeViewerHandler,
+        PORT,
+        '👁️  Tilt IDE Code Viewer',
+        '📄 Open files from the file browser to view with syntax highlighting'
+    )
+
+
+if __name__ == '__main__':
+    main()