aios-core 2.1.0

package/.aios-core/docs/troubleshooting-guide.md

@@ -0,0 +1,625 @@
+# AIOS-FULLSTACK Meta-Agent Troubleshooting Guide
+
+## Overview
+
+This guide helps diagnose and resolve common issues when using the AIOS-FULLSTACK meta-agent for component creation and management.
+
+## Table of Contents
+
+1. [Component Creation Issues](#component-creation-issues)
+2. [Template Processing Problems](#template-processing-problems)
+3. [Elicitation Workflow Issues](#elicitation-workflow-issues)
+4. [Security Validation Errors](#security-validation-errors)
+5. [Transaction and Rollback Problems](#transaction-and-rollback-problems)
+6. [Batch Creation Failures](#batch-creation-failures)
+7. [Dependency Resolution Issues](#dependency-resolution-issues)
+8. [Performance Problems](#performance-problems)
+9. [Debug Techniques](#debug-techniques)
+
+## Component Creation Issues
+
+### Issue: "Component already exists"
+
+**Symptoms:**
+```
+❌ Error: Agent 'data-analyst' already exists at /aios-core/agents/data-analyst.md
+```
+
+**Causes:**
+- Component with same name already created
+- Previous creation attempt partially succeeded
+
+**Solutions:**
+1. Choose a different name:
+   ```bash
+   *create-agent
+   ? Agent name: data-analyst-v2
+   ```
+
+2. Check existing components:
+   ```bash
+   ls aios-core/agents/
+   ```
+
+3. If overwriting is intended:
+   ```bash
+   # Remove existing component first
+   rm aios-core/agents/data-analyst.md
+   *create-agent
+   ```
+
+### Issue: "Invalid name format"
+
+**Symptoms:**
+```
+❌ Name must be lowercase with hyphens only
+```
+
+**Causes:**
+- Using uppercase letters
+- Spaces or underscores in name
+- Starting with number
+
+**Solutions:**
+1. Follow naming conventions:
+   - ✅ Good: `data-analyst`, `api-tester`, `log-monitor`
+   - ❌ Bad: `DataAnalyst`, `api_tester`, `log monitor`, `2-analyzer`
+
+2. Use the transformer:
+   ```javascript
+   // Name transformer logic
+   const validName = inputName
+     .toLowerCase()
+     .replace(/\s+/g, '-')
+     .replace(/[^a-z0-9-]/g, '')
+     .replace(/^[0-9]/, '');
+   ```
+
+### Issue: "Template not found"
+
+**Symptoms:**
+```
+❌ Error: Template not found: agent-template.yaml
+```
+
+**Causes:**
+- Missing template files
+- Incorrect installation
+- Wrong working directory
+
+**Solutions:**
+1. Verify template location:
+   ```bash
+   ls aios-core/templates/
+   # Should see: agent-template.yaml, task-template.md, workflow-template.yaml
+   ```
+
+2. Reinstall templates:
+   ```bash
+   # From project root
+   npm run setup:templates
+   ```
+
+3. Check working directory:
+   ```bash
+   pwd
+   # Should be in aios-fullstack root
+   ```
+
+## Template Processing Problems
+
+### Issue: Variables not replaced
+
+**Symptoms:**
+```
+Generated content contains: {{AGENT_NAME}} instead of actual value
+```
+
+**Causes:**
+- Missing variables in elicitation
+- Typo in variable names
+- Template syntax errors
+
+**Solutions:**
+1. Enable debug mode:
+   ```bash
+   DEBUG_TEMPLATES=true *create-agent
+   ```
+
+2. Check variable mapping:
+   ```javascript
+   // Common variable mappings
+   {
+     AGENT_NAME: answers.agentName,
+     AGENT_TITLE: answers.agentTitle,
+     WHEN_TO_USE: answers.whenToUse
+   }
+   ```
+
+3. Validate template syntax:
+   - Opening tag: `{{#IF_VARIABLE}}`
+   - Closing tag: `{{/IF_VARIABLE}}`
+   - Variable: `{{VARIABLE_NAME}}`
+
+### Issue: Malformed output
+
+**Symptoms:**
+- Broken YAML structure
+- Missing sections
+- Incorrect indentation
+
+**Causes:**
+- Template indentation issues
+- Conditional logic errors
+- Special characters in input
+
+**Solutions:**
+1. Check template indentation:
+   ```yaml
+   {{#IF_COMMANDS}}
+   commands:
+   {{#EACH_COMMANDS}}
+     - name: {{COMMAND_NAME}}  # Note the spacing
+   {{/EACH_COMMANDS}}
+   {{/IF_COMMANDS}}
+   ```
+
+2. Escape special characters:
+   ```javascript
+   const escaped = input
+     .replace(/"/g, '\\"')
+     .replace(/\n/g, '\\n');
+   ```
+
+## Elicitation Workflow Issues
+
+### Issue: Prompts not appearing
+
+**Symptoms:**
+- Command exits immediately
+- No interactive prompts shown
+
+**Causes:**
+- Non-interactive terminal
+- Mock mode enabled
+- Input stream issues
+
+**Solutions:**
+1. Ensure interactive terminal:
+   ```bash
+   # Force interactive mode
+   *create-agent --interactive
+   ```
+
+2. Check mock mode:
+   ```javascript
+   // In elicitation-engine.js
+   if (this.mockMode) {
+     console.log('Mock mode is enabled');
+   }
+   ```
+
+3. Reset terminal:
+   ```bash
+   reset
+   *create-agent
+   ```
+
+### Issue: Session not saving
+
+**Symptoms:**
+```
+⚠️ Warning: Failed to save elicitation session
+```
+
+**Causes:**
+- Missing session directory
+- Permissions issues
+- Disk space
+
+**Solutions:**
+1. Create session directory:
+   ```bash
+   mkdir -p aios-core/.sessions
+   ```
+
+2. Check permissions:
+   ```bash
+   chmod 755 aios-core/.sessions
+   ```
+
+3. Verify disk space:
+   ```bash
+   df -h .
+   ```
+
+## Security Validation Errors
+
+### Issue: "Security check failed"
+
+**Symptoms:**
+```
+❌ Security check failed: Potential code injection detected
+```
+
+**Causes:**
+- Script tags in input
+- Executable code patterns
+- Suspicious file paths
+
+**Solutions:**
+1. Avoid code in descriptions:
+   - ❌ Bad: `Executes <script>alert('hi')</script>`
+   - ✅ Good: `Processes user alerts`
+
+2. Use plain text:
+   ```
+   ? Description: Analyzes log files for errors
+   # Not: Runs `grep -E "error|fail" *.log`
+   ```
+
+3. Check security rules:
+   ```javascript
+   // In security-checker.js
+   const forbidden = [
+     /<script/i,
+     /eval\(/,
+     /require\(['"]\./,
+     /\.\.\//
+   ];
+   ```
+
+### Issue: "Path traversal detected"
+
+**Symptoms:**
+```
+❌ Security: Path traversal attempt detected
+```
+
+**Causes:**
+- Using `../` in paths
+- Absolute paths outside project
+- Symbolic link attempts
+
+**Solutions:**
+1. Use relative paths within project:
+   ```javascript
+   // Good
+   path.join(this.rootPath, 'agents', 'my-agent.md')
+   
+   // Bad
+   path.join('../../../', 'agents', 'my-agent.md')
+   ```
+
+2. Validate paths:
+   ```javascript
+   const safePath = path.normalize(inputPath);
+   if (!safePath.startsWith(this.rootPath)) {
+     throw new Error('Path outside project');
+   }
+   ```
+
+## Transaction and Rollback Problems
+
+### Issue: "No transaction to rollback"
+
+**Symptoms:**
+```
+⚠️ No transactions found to rollback
+```
+
+**Causes:**
+- Transaction already rolled back
+- Transaction logs deleted
+- No recent operations
+
+**Solutions:**
+1. List available transactions:
+   ```bash
+   *list-transactions
+   ```
+
+2. Check transaction directory:
+   ```bash
+   ls aios-core/logs/transactions/
+   ```
+
+3. Use specific transaction ID:
+   ```bash
+   *undo-last --transaction-id=txn-1234567890-abcd
+   ```
+
+### Issue: Partial rollback failure
+
+**Symptoms:**
+```
+✅ Successful: 3
+❌ Failed: 2
+   - file1.md: Permission denied
+   - manifest.yaml: File not found
+```
+
+**Causes:**
+- Files modified after creation
+- Missing backup files
+- Permission changes
+
+**Solutions:**
+1. Manual cleanup:
+   ```bash
+   # Check failed files
+   ls -la aios-core/agents/file1.md
+   
+   # Remove manually if needed
+   rm aios-core/agents/file1.md
+   ```
+
+2. Force rollback:
+   ```bash
+   *undo-last --force --continue-on-error
+   ```
+
+3. Restore from backup:
+   ```bash
+   # Check backups
+   ls aios-core/logs/transactions/txn-*/backups/
+   ```
+
+## Batch Creation Failures
+
+### Issue: "Circular dependency detected"
+
+**Symptoms:**
+```
+❌ Circular dependency detected: A → B → C → A
+```
+
+**Causes:**
+- Tasks depending on each other
+- Workflow referencing itself
+- Complex dependency chains
+
+**Solutions:**
+1. Review dependencies:
+   ```javascript
+   // Check dependency graph
+   {
+     "task-a": ["task-b"],
+     "task-b": ["task-c"],
+     "task-c": ["task-a"]  // Circular!
+   }
+   ```
+
+2. Break circular chains:
+   - Remove unnecessary dependencies
+   - Create intermediate tasks
+   - Use conditional dependencies
+
+3. Visualize dependencies:
+   ```bash
+   *analyze-dependencies --visual
+   ```
+
+### Issue: Batch creation partially fails
+
+**Symptoms:**
+```
+📦 Creating components [████████░░░░░░░░░░] 45% 5/11
+❌ Some components failed to create
+```
+
+**Causes:**
+- Individual component errors
+- Dependency not met
+- Resource constraints
+
+**Solutions:**
+1. Check failure details:
+   ```bash
+   # Review transaction log
+   cat aios-core/logs/transactions/latest.json
+   ```
+
+2. Rollback and retry:
+   ```bash
+   *undo-last
+   # Fix issues
+   *create-suite --continue-from=component-6
+   ```
+
+3. Create individually:
+   ```bash
+   # Skip batch, create one by one
+   *create-agent
+   *create-task
+   ```
+
+## Dependency Resolution Issues
+
+### Issue: "Missing dependencies"
+
+**Symptoms:**
+```
+⚠️ Task 'analyze-data' requires agent 'data-analyst' which doesn't exist
+```
+
+**Causes:**
+- Creating task before agent
+- Typo in agent name
+- Deleted dependencies
+
+**Solutions:**
+1. Check existing components:
+   ```bash
+   *list-components --type=agent
+   ```
+
+2. Create missing dependencies:
+   ```bash
+   *create-agent
+   ? Agent name: data-analyst
+   ```
+
+3. Use batch creation:
+   ```bash
+   *create-suite
+   > Complete Agent Package
+   ```
+
+## Performance Problems
+
+### Issue: Slow component creation
+
+**Symptoms:**
+- Creation takes > 30 seconds
+- Terminal freezes
+- High CPU usage
+
+**Causes:**
+- Large template files
+- Complex validation
+- Disk I/O issues
+
+**Solutions:**
+1. Profile performance:
+   ```bash
+   DEBUG=perf:* *create-agent
+   ```
+
+2. Optimize templates:
+   - Reduce template size
+   - Simplify conditionals
+   - Cache processed templates
+
+3. Check system resources:
+   ```bash
+   # CPU usage
+   top
+   
+   # Disk I/O
+   iostat -x 1
+   ```
+
+### Issue: Memory usage high
+
+**Symptoms:**
+```
+FATAL ERROR: JavaScript heap out of memory
+```
+
+**Causes:**
+- Large batch operations
+- Memory leaks
+- Circular references
+
+**Solutions:**
+1. Increase Node memory:
+   ```bash
+   NODE_OPTIONS="--max-old-space-size=4096" *create-suite
+   ```
+
+2. Reduce batch size:
+   ```javascript
+   // In batch-creator.js
+   options.batchSize = 5; // Instead of 50
+   ```
+
+3. Clear caches:
+   ```bash
+   rm -rf aios-core/.cache/
+   ```
+
+## Debug Techniques
+
+### Enable Debug Output
+
+```bash
+# All debug output
+DEBUG=* *create-agent
+
+# Specific modules
+DEBUG=aios:template,aios:elicitation *create-agent
+
+# Performance timing
+DEBUG=perf:* *create-agent
+```
+
+### Check Logs
+
+```bash
+# Application logs
+tail -f aios-core/logs/aios-developer.log
+
+# Transaction logs
+ls -la aios-core/logs/transactions/
+
+# Error logs
+grep ERROR aios-core/logs/*.log
+```
+
+### Validate Components
+
+```bash
+# Validate single component
+*validate-component --type=agent --name=data-analyst
+
+# Validate all components
+*validate-all --fix-issues
+```
+
+### Test Mode
+
+```bash
+# Dry run without creating files
+*create-agent --dry-run
+
+# Test with mock data
+*create-agent --test-mode
+```
+
+## Getting Help
+
+### Built-in Help
+
+```bash
+# General help
+*help
+
+# Command-specific help
+*help create-agent
+*help create-suite
+*help undo-last
+```
+
+### Documentation
+
+- Template syntax: `aios-core/docs/template-syntax.md`
+- Creation guide: `aios-core/docs/component-creation-guide.md`
+- API reference: `aios-core/docs/api-reference.md`
+
+### Support Channels
+
+1. **Check existing issues**: Review known problems
+2. **Enable debug mode**: Gather diagnostic info
+3. **Collect logs**: Include relevant error messages
+4. **Minimal reproduction**: Create simple test case
+
+### Emergency Recovery
+
+If all else fails:
+
+1. **Backup current state**:
+   ```bash
+   tar -czf aios-backup.tar.gz aios-core/
+   ```
+
+2. **Reset to clean state**:
+   ```bash
+   git checkout -- aios-core/
+   npm run setup
+   ```
+
+3. **Restore from transaction logs**:
+   ```bash
+   *restore-from-transaction --id=last-known-good
+   ```