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
298
.dss/DEBUG_QUICKSTART.md
Normal file
298
.dss/DEBUG_QUICKSTART.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# DSS Debug Inspector - Quick Start Guide
|
||||
|
||||
## Getting Started (2 minutes)
|
||||
|
||||
### 1. Open Browser DevTools
|
||||
Press **F12** in your browser on the DSS dashboard
|
||||
|
||||
### 2. Go to Console Tab
|
||||
Click the "Console" tab at the top
|
||||
|
||||
### 3. Access Debug Inspector
|
||||
Type in the console:
|
||||
```javascript
|
||||
window.__DSS_DEBUG.help()
|
||||
```
|
||||
|
||||
This shows you all available commands.
|
||||
|
||||
---
|
||||
|
||||
## Common Debugging Tasks
|
||||
|
||||
### "My Dashboard Won't Load"
|
||||
|
||||
1. In console:
|
||||
```javascript
|
||||
window.__DSS_DEBUG.printDiagnosis()
|
||||
```
|
||||
|
||||
2. Look for:
|
||||
- Any errors in "Recent Activity"
|
||||
- "Crash Detected" section
|
||||
- Available recovery points
|
||||
|
||||
3. If crash detected, recover:
|
||||
```javascript
|
||||
const report = window.__DSS_DEBUG.errorRecovery.getCrashReport();
|
||||
if (report.recoveryPoints.length > 0) {
|
||||
window.__DSS_DEBUG.errorRecovery.recover(
|
||||
report.recoveryPoints[report.recoveryPoints.length - 1].id
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "The Dashboard is Slow"
|
||||
|
||||
1. In console:
|
||||
```javascript
|
||||
const metrics = window.__DSS_DEBUG.getPerformanceMetrics();
|
||||
console.table(metrics.slowCallDetails);
|
||||
```
|
||||
|
||||
2. Look for:
|
||||
- Which endpoints are slow (> 1000ms)
|
||||
- How many API calls are happening
|
||||
- Any failed calls
|
||||
|
||||
3. Example output:
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ endpoint │ method │ duration │ status │
|
||||
├─────────────────────────────────────────┤
|
||||
│ /api/figma │ GET │ 2500ms │ 200 │
|
||||
│ /api/config │ GET │ 1200ms │ 200 │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "I Got an Error"
|
||||
|
||||
1. Check the error:
|
||||
```javascript
|
||||
const crashReport = window.__DSS_DEBUG.errorRecovery.getCrashReport();
|
||||
console.log(crashReport.error);
|
||||
```
|
||||
|
||||
2. See what state you were in:
|
||||
```javascript
|
||||
const snapshots = window.__DSS_DEBUG.workflowPersistence.getSnapshots();
|
||||
const lastSnapshot = snapshots[snapshots.length - 1];
|
||||
console.log(lastSnapshot.state);
|
||||
```
|
||||
|
||||
3. Find what triggered it:
|
||||
```javascript
|
||||
const logs = window.__DSS_DEBUG.findLogs({ level: 'error' });
|
||||
console.table(logs.slice(-5));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "Feature X Isn't Working"
|
||||
|
||||
1. Trace the action:
|
||||
```javascript
|
||||
const logs = window.__DSS_DEBUG.findLogs('feature-name');
|
||||
console.table(logs);
|
||||
```
|
||||
|
||||
2. Check permissions:
|
||||
```javascript
|
||||
const logs = window.__DSS_DEBUG.findLogs({
|
||||
action: 'permission_check',
|
||||
level: 'warning'
|
||||
});
|
||||
console.table(logs);
|
||||
```
|
||||
|
||||
3. Check current user role:
|
||||
```javascript
|
||||
const snapshot = window.__DSS_DEBUG.workflowPersistence.getSnapshots().pop();
|
||||
console.log('User role:', snapshot.state.user.role);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### "I Need to Send Debug Info to Developer"
|
||||
|
||||
1. Export everything:
|
||||
```javascript
|
||||
const data = window.__DSS_DEBUG.exportDebugData();
|
||||
```
|
||||
|
||||
This copies all debugging data to your clipboard as JSON.
|
||||
|
||||
2. Paste it in an email or issue report (it's JSON, safe to share)
|
||||
|
||||
---
|
||||
|
||||
## Available Commands Reference
|
||||
|
||||
### Diagnostics
|
||||
```javascript
|
||||
// Quick overview
|
||||
window.__DSS_DEBUG.printDiagnosis()
|
||||
|
||||
// Detailed overview
|
||||
window.__DSS_DEBUG.quickDiagnosis()
|
||||
|
||||
// Show help
|
||||
window.__DSS_DEBUG.help()
|
||||
```
|
||||
|
||||
### Search Logs
|
||||
```javascript
|
||||
// By pattern
|
||||
window.__DSS_DEBUG.findLogs('api_call')
|
||||
|
||||
// By filters
|
||||
window.__DSS_DEBUG.findLogs({
|
||||
action: 'api_call',
|
||||
level: 'error',
|
||||
timeRange: {
|
||||
start: Date.now() - 60000, // Last minute
|
||||
end: Date.now()
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Audit Logs
|
||||
```javascript
|
||||
// All logs
|
||||
window.__DSS_DEBUG.auditLogger.getLogs()
|
||||
|
||||
// Filtered logs
|
||||
window.__DSS_DEBUG.auditLogger.getLogs({
|
||||
action: 'page_change',
|
||||
level: 'info'
|
||||
})
|
||||
|
||||
// Statistics
|
||||
window.__DSS_DEBUG.auditLogger.getStats()
|
||||
```
|
||||
|
||||
### Snapshots
|
||||
```javascript
|
||||
// All snapshots
|
||||
window.__DSS_DEBUG.workflowPersistence.getSnapshots()
|
||||
|
||||
// Last snapshot
|
||||
const snapshots = window.__DSS_DEBUG.workflowPersistence.getSnapshots();
|
||||
snapshots[snapshots.length - 1]
|
||||
|
||||
// Restore to snapshot
|
||||
window.__DSS_DEBUG.workflowPersistence.restoreSnapshot('snapshot-id')
|
||||
```
|
||||
|
||||
### Error Recovery
|
||||
```javascript
|
||||
// Full crash report
|
||||
window.__DSS_DEBUG.errorRecovery.getCrashReport()
|
||||
|
||||
// Recover
|
||||
window.__DSS_DEBUG.errorRecovery.recover('recovery-point-id')
|
||||
```
|
||||
|
||||
### Performance
|
||||
```javascript
|
||||
// All metrics
|
||||
window.__DSS_DEBUG.getPerformanceMetrics()
|
||||
|
||||
// Export everything
|
||||
window.__DSS_DEBUG.exportDebugData()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips & Tricks
|
||||
|
||||
### 1. Clear Console, Run Diagnosis
|
||||
```javascript
|
||||
console.clear();
|
||||
window.__DSS_DEBUG.printDiagnosis();
|
||||
```
|
||||
|
||||
### 2. Watch for New Errors
|
||||
```javascript
|
||||
// Get current error count
|
||||
const before = window.__DSS_DEBUG.findLogs({ level: 'error' }).length;
|
||||
|
||||
// Do something that might fail...
|
||||
|
||||
// Check if new errors
|
||||
const after = window.__DSS_DEBUG.findLogs({ level: 'error' }).length;
|
||||
console.log(`New errors: ${after - before}`);
|
||||
```
|
||||
|
||||
### 3. Compare Before and After State
|
||||
```javascript
|
||||
const before = window.__DSS_DEBUG.workflowPersistence.getSnapshots()[0];
|
||||
const after = window.__DSS_DEBUG.workflowPersistence.getSnapshots().pop();
|
||||
|
||||
console.log('Changes:');
|
||||
console.log('Before:', before.state.currentPage);
|
||||
console.log('After:', after.state.currentPage);
|
||||
```
|
||||
|
||||
### 4. Monitor API Performance Over Time
|
||||
```javascript
|
||||
setInterval(() => {
|
||||
const metrics = window.__DSS_DEBUG.getPerformanceMetrics();
|
||||
console.log(`Avg API time: ${Math.round(metrics.averageResponseTime)}ms`);
|
||||
}, 5000);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What to Look For
|
||||
|
||||
### Signs of Problems
|
||||
- ❌ Errors in "Recent Activity" section
|
||||
- ❌ "Crash Detected" = true
|
||||
- ❌ Failed API calls (status >= 400)
|
||||
- ❌ Slow API calls (duration > 1000ms)
|
||||
- ❌ Permission warnings (level: 'warning')
|
||||
|
||||
### Signs of Health
|
||||
- ✅ No crashes detected
|
||||
- ✅ Recent activity shows expected actions
|
||||
- ✅ All API calls successful (status 200)
|
||||
- ✅ Fast response times (< 500ms average)
|
||||
- ✅ User role matches expected access level
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Share Diagnosis**: If there's an issue, run:
|
||||
```javascript
|
||||
window.__DSS_DEBUG.exportDebugData()
|
||||
```
|
||||
And share the JSON output
|
||||
|
||||
2. **Report Pattern**: Include:
|
||||
- What you were doing
|
||||
- Console output from diagnosis
|
||||
- Performance metrics
|
||||
- Recent activity logs
|
||||
|
||||
3. **Check Documentation**: See full details in:
|
||||
- `.dss/DSS_SELF_DEBUG_METHODOLOGY.md`
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you see an error or issue:
|
||||
|
||||
1. Run diagnostic
|
||||
2. Look for error messages
|
||||
3. Check recovery points
|
||||
4. Export debug data
|
||||
5. Share with development team
|
||||
|
||||
Everything the system recorded is available in the console.
|
||||
Reference in New Issue
Block a user