Initial commit: Clean DSS implementation
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
313
.dss/WORKFLOWS/01-capture-browser-logs.md
Normal file
313
.dss/WORKFLOWS/01-capture-browser-logs.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# Workflow 01: Capture Browser Logs
|
||||
|
||||
**Purpose**: Capture and retrieve all browser-side logs from DSS dashboard for debugging
|
||||
|
||||
**When to Use**:
|
||||
- User reports dashboard not loading
|
||||
- JavaScript errors in browser
|
||||
- Network request failures
|
||||
- Performance issues
|
||||
- Configuration problems
|
||||
|
||||
**Estimated Time**: 2-5 minutes
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Dashboard accessible (https://dss.overbits.luz.uy/ or http://localhost:3456/admin-ui/index.html)
|
||||
- Browser DevTools available (Chrome, Firefox, Edge, Safari)
|
||||
- Browser logger module loaded (browser-logger.js)
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Procedure
|
||||
|
||||
### Step 1: Open DSS Dashboard
|
||||
|
||||
**Action**:
|
||||
```
|
||||
Navigate to: https://dss.overbits.luz.uy/
|
||||
Or local: http://localhost:3456/admin-ui/index.html
|
||||
```
|
||||
|
||||
**Expected Result**: Dashboard loads (may require credentials)
|
||||
|
||||
**Troubleshooting**:
|
||||
- If 401 Unauthorized: Provide htpasswd credentials
|
||||
- If connection refused: Check API server running on port 3456
|
||||
- If 500 error: Check server logs with `journalctl -u dss-api -f`
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Open Browser DevTools
|
||||
|
||||
**Action**:
|
||||
```
|
||||
Chrome/Edge: F12 or Cmd+Option+I (Mac) or Ctrl+Shift+I (Windows)
|
||||
Firefox: F12 or Cmd+Option+K (Mac) or Ctrl+Shift+K (Windows)
|
||||
Safari: Cmd+Option+C (Mac, requires enabling in Preferences)
|
||||
```
|
||||
|
||||
**Expected Result**: DevTools panel opens at bottom or side of browser
|
||||
|
||||
**Go to Console Tab**: Click "Console" in the top menu of DevTools
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Verify Browser Logger is Loaded
|
||||
|
||||
**Action**:
|
||||
```javascript
|
||||
// In console, type:
|
||||
window.__DSS_BROWSER_LOGS
|
||||
```
|
||||
|
||||
**Expected Result**:
|
||||
```javascript
|
||||
{
|
||||
all: ƒ (),
|
||||
errors: ƒ (),
|
||||
network: ƒ (),
|
||||
diagnostic: ƒ (),
|
||||
export: ƒ (),
|
||||
print: ƒ (),
|
||||
clear: ƒ ()
|
||||
}
|
||||
```
|
||||
|
||||
**Troubleshooting**:
|
||||
- If `undefined`: Browser logger not loaded. Check Network tab for `/admin-ui/js/core/browser-logger.js` (should be 200 OK)
|
||||
- If 404 on browser-logger.js: File not imported in index.html
|
||||
- Manually load: `import('/admin-ui/js/core/browser-logger.js').then(() => console.log('Loaded'))`
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Get Diagnostic Summary
|
||||
|
||||
**Action**:
|
||||
```javascript
|
||||
window.__DSS_BROWSER_LOGS.diagnostic()
|
||||
```
|
||||
|
||||
**Expected Result**:
|
||||
```javascript
|
||||
{
|
||||
sessionId: "session-1733456789-xyz123",
|
||||
uptime: 45230, // ms since page load
|
||||
totalLogs: 127,
|
||||
errorCount: 3,
|
||||
warnCount: 5,
|
||||
networkRequests: 12,
|
||||
memory: {
|
||||
usedJSHeapSize: 15728640,
|
||||
jsHeapSizeLimit: 2172649472,
|
||||
usagePercent: "0.72"
|
||||
},
|
||||
url: "https://dss.overbits.luz.uy/",
|
||||
userAgent: "Mozilla/5.0...",
|
||||
recentErrors: [...], // Last 5 errors
|
||||
recentNetworkRequests: [...] // Last 5 requests
|
||||
}
|
||||
```
|
||||
|
||||
**Analysis**:
|
||||
- `errorCount > 0`: Check recentErrors for critical issues
|
||||
- `networkRequests == 0`: No API calls made (possible config issue)
|
||||
- `usagePercent > 80`: Memory leak or performance issue
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Retrieve Specific Log Types
|
||||
|
||||
**Get All Errors**:
|
||||
```javascript
|
||||
window.__DSS_BROWSER_LOGS.errors()
|
||||
```
|
||||
|
||||
**Get Network Activity**:
|
||||
```javascript
|
||||
window.__DSS_BROWSER_LOGS.network()
|
||||
```
|
||||
|
||||
**Get All Logs**:
|
||||
```javascript
|
||||
window.__DSS_BROWSER_LOGS.all()
|
||||
```
|
||||
|
||||
**Expected Result**: Array of log entries with timestamps, levels, categories, messages, and data
|
||||
|
||||
**Analysis Tips**:
|
||||
- Look for `level: 'error'` entries first
|
||||
- Check `category: 'fetchError'` for failed API calls
|
||||
- Check `status: 404` or `status: 500` in network logs
|
||||
- Check `category: 'uncaughtError'` for JavaScript exceptions
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Search for Specific Issues
|
||||
|
||||
**Search by Keyword**:
|
||||
```javascript
|
||||
window.__DSS_BROWSER_LOGGER.getLogs({
|
||||
search: 'config', // Search term
|
||||
level: 'error', // Filter by level
|
||||
limit: 50 // Max results
|
||||
})
|
||||
```
|
||||
|
||||
**Search by Time Range**:
|
||||
```javascript
|
||||
const oneHourAgo = Date.now() - (60 * 60 * 1000);
|
||||
window.__DSS_BROWSER_LOGGER.getLogs({
|
||||
minTime: oneHourAgo,
|
||||
limit: 100
|
||||
})
|
||||
```
|
||||
|
||||
**Expected Result**: Filtered log entries matching criteria
|
||||
|
||||
---
|
||||
|
||||
### Step 7: Export Logs for Analysis
|
||||
|
||||
**Export as JSON**:
|
||||
```javascript
|
||||
const data = window.__DSS_BROWSER_LOGS.export();
|
||||
console.log(JSON.stringify(data, null, 2));
|
||||
```
|
||||
|
||||
**Download to File**:
|
||||
```javascript
|
||||
const data = window.__DSS_BROWSER_LOGS.export();
|
||||
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
|
||||
const url = URL.createObjectURL(blob);
|
||||
const a = document.createElement('a');
|
||||
a.href = url;
|
||||
a.download = 'dss-browser-logs-' + Date.now() + '.json';
|
||||
a.click();
|
||||
```
|
||||
|
||||
**Expected Result**:
|
||||
- JSON export displays in console
|
||||
- File downloads with name like `dss-browser-logs-1733456789000.json`
|
||||
|
||||
---
|
||||
|
||||
### Step 8: Send Logs to Server (Optional)
|
||||
|
||||
**Manual Upload**:
|
||||
```javascript
|
||||
const logs = window.__DSS_BROWSER_LOGS.export();
|
||||
fetch('/api/browser-logs', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(logs)
|
||||
}).then(r => r.json()).then(console.log);
|
||||
```
|
||||
|
||||
**Expected Result**:
|
||||
```json
|
||||
{
|
||||
"status": "stored",
|
||||
"sessionId": "session-1733456789-xyz123"
|
||||
}
|
||||
```
|
||||
|
||||
**Retrieve from Server**:
|
||||
```bash
|
||||
curl http://localhost:3456/api/browser-logs/session-1733456789-xyz123
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue 1: No Logs Captured
|
||||
|
||||
**Symptoms**: `totalLogs: 0` or empty arrays
|
||||
|
||||
**Causes**:
|
||||
- Browser logger loaded after app initialized
|
||||
- Logger not intercepting console calls
|
||||
- Storage disabled (private browsing)
|
||||
|
||||
**Solution**:
|
||||
1. Reload page with DevTools open
|
||||
2. Check browser-logger.js import order (should be first)
|
||||
3. Check console for storage errors
|
||||
|
||||
---
|
||||
|
||||
### Issue 2: Logs Not Persisting Across Reloads
|
||||
|
||||
**Symptoms**: Logs disappear on page refresh
|
||||
|
||||
**Causes**:
|
||||
- sessionStorage disabled
|
||||
- Private/Incognito mode
|
||||
- Storage quota exceeded
|
||||
|
||||
**Solution**:
|
||||
1. Check browser privacy settings
|
||||
2. Use regular browsing mode
|
||||
3. Clear old logs: `window.__DSS_BROWSER_LOGS.clear()`
|
||||
|
||||
---
|
||||
|
||||
### Issue 3: Network Logs Missing
|
||||
|
||||
**Symptoms**: `networkRequests: 0` but API calls visible in Network tab
|
||||
|
||||
**Causes**:
|
||||
- Browser logger loaded after fetch calls
|
||||
- Using XMLHttpRequest instead of fetch
|
||||
- API calls made before logger init
|
||||
|
||||
**Solution**:
|
||||
1. Ensure browser-logger.js is first script loaded
|
||||
2. Reload page to capture from start
|
||||
3. Check if app uses XMLHttpRequest (not currently intercepted)
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- ✅ Diagnostic shows session info and uptime
|
||||
- ✅ Logs captured for errors, warnings, network requests
|
||||
- ✅ Can export logs as JSON
|
||||
- ✅ Can search and filter logs
|
||||
- ✅ Memory usage tracked
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After capturing browser logs:
|
||||
|
||||
1. **If errors found**: Use Workflow 02 (Diagnose Errors)
|
||||
2. **If performance issues**: Use Workflow 03 (Debug Performance)
|
||||
3. **If API failures**: Check server logs with `journalctl -u dss-api -f`
|
||||
4. **If configuration issues**: Check `/api/config` endpoint response
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `.dss/BROWSER_LOG_CAPTURE_PROCEDURE.md` - Detailed browser logger documentation
|
||||
- `.dss/GET_BROWSER_LOGS.sh` - Quick reference hook script
|
||||
- `admin-ui/js/core/browser-logger.js` - Logger source code
|
||||
- `.dss/MCP_DEBUG_TOOLS_ARCHITECTURE.md` - Overall debug architecture
|
||||
|
||||
---
|
||||
|
||||
## MCP Tool Access
|
||||
|
||||
**From Claude Code**:
|
||||
```
|
||||
Use tool: dss_get_browser_diagnostic
|
||||
Or: dss_get_browser_errors
|
||||
Or: dss_get_browser_network
|
||||
```
|
||||
|
||||
These MCP tools automatically retrieve browser logs via the API layer.
|
||||
Reference in New Issue
Block a user