crewx 0.1.1 → 0.1.2

package/docs/troubleshooting.md

@@ -0,0 +1,585 @@
+# Troubleshooting Guide
+
+Common issues and solutions for CrewX.
+
+## Installation Issues
+
+### Command Not Found
+
+**Problem:** `crewx: command not found`
+
+**Solution:**
+```bash
+# Install globally
+npm install -g crewx
+
+# Verify installation
+crewx --version
+
+# Check PATH
+echo $PATH | grep npm
+```
+
+### Permission Errors (macOS/Linux)
+
+**Problem:** Permission denied during installation
+
+**Solution:**
+```bash
+# Use sudo (not recommended)
+sudo npm install -g crewx
+
+# Better: Fix npm permissions
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# Then install
+npm install -g crewx
+```
+
+## Windows-Specific Issues
+
+### PowerShell Execution Policy
+
+**Problem:** `'crewx' is not recognized as an internal or external command`
+
+**Cause:** PowerShell execution policy restrictions prevent `npx` scripts.
+
+**Solution 1 (Recommended): Use cmd.exe**
+
+Update MCP configuration:
+```json
+{
+  "servers": {
+    "crewx": {
+      "command": "cmd.exe",
+      "args": ["/c", "crewx", "mcp"],
+      "env": {
+        "CREWX_CONFIG": "${workspaceFolder}/crewx.yaml"
+      }
+    }
+  }
+}
+```
+
+**Solution 2: Change execution policy (requires admin)**
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+**Solution 3: Direct node execution**
+```bash
+# Install globally
+npm install -g crewx
+
+# Find installation path
+npm root -g
+
+# Update MCP config
+{
+  "servers": {
+    "crewx": {
+      "command": "node",
+      "args": ["C:\\Users\\YourName\\AppData\\Roaming\\npm\\node_modules\\crewx\\dist\\main.js", "mcp"]
+    }
+  }
+}
+```
+
+## Configuration Issues
+
+### Configuration File Not Found
+
+**Problem:** `Error: crewx.yaml not found` (or `agents.yaml not found`)
+
+**Solution:**
+```bash
+# Create crewx.yaml (preferred)
+crewx init
+
+# Verify file exists
+ls crewx.yaml
+
+# Check MCP config points to correct path
+cat .vscode/mcp.json  # or Claude Desktop config
+```
+
+> **Note:** Both `crewx.yaml` (preferred) and `agents.yaml` (legacy) are supported.
+
+### Invalid YAML Syntax
+
+**Problem:** `Error: Invalid YAML syntax`
+
+**Solution:**
+```bash
+# Run doctor to validate
+crewx doctor
+
+# Common YAML errors:
+# - Incorrect indentation (use spaces, not tabs)
+# - Missing quotes around special characters
+# - Missing colons or dashes
+```
+
+**Valid YAML:**
+```yaml
+agents:
+  - id: "my_agent"      # ✓ Correct indentation
+    name: "My Agent"    # ✓ Quotes around strings
+    provider: "claude"  # ✓ Proper spacing
+```
+
+**Invalid YAML:**
+```yaml
+agents:
+- id: my_agent         # ✗ No quotes (may break with special chars)
+  name: My Agent       # ✗ No quotes
+   provider: claude    # ✗ Wrong indentation
+```
+
+## MCP Integration Issues
+
+### MCP Server Won't Start
+
+**Problem:** MCP server fails to start in VS Code/Claude Desktop
+
+**Checklist:**
+1. Verify `crewx.yaml` (or `agents.yaml`) exists at specified path
+2. Check CrewX is installed: `crewx --version`
+3. Validate MCP config syntax (valid JSON)
+4. Check environment variable `CREWX_CONFIG` is set
+5. Restart MCP client after config changes
+
+**Debugging:**
+```bash
+# Test MCP server manually
+crewx mcp
+
+# Check for error messages
+# Verify config file path is correct
+cat $CREWX_CONFIG
+```
+
+### MCP Tools Not Appearing
+
+**Problem:** CrewX tools don't show up in MCP client
+
+**Solution:**
+1. Restart MCP client (VS Code, Claude Desktop, etc.)
+2. Check MCP client logs for connection errors
+3. Verify `CREWX_CONFIG` environment variable
+4. Test server manually: `crewx mcp`
+
+**VS Code specific:**
+```bash
+# Check VS Code MCP logs
+# View > Output > Select "MCP" from dropdown
+```
+
+## AI Provider Issues
+
+### Provider Not Available
+
+**Problem:** `Error: AI provider not available`
+
+**Solution:**
+```bash
+# Check provider status
+crewx doctor
+
+# Verify CLI tools are installed
+claude --version
+gemini --version
+gh copilot --version
+
+# Install missing tools
+npm install -g @anthropic/claude-code
+npm install -g @google/generative-ai-cli
+gh extension install github/gh-copilot
+```
+
+### Provider Authentication Failed
+
+**Problem:** Authentication errors with AI providers
+
+**Claude Code:**
+```bash
+# Re-authenticate
+claude login
+
+# Verify session
+claude session
+```
+
+**Gemini CLI:**
+```bash
+# Set API key
+export GOOGLE_API_KEY="your-api-key"
+
+# Or configure
+gemini config set apiKey YOUR_API_KEY
+```
+
+**Copilot CLI:**
+```bash
+# Re-authenticate
+gh auth login
+
+# Verify
+gh auth status
+```
+
+### Session Limit Reached
+
+**Problem:** `Error: Session limit reached`
+
+**Solution:**
+```bash
+# Wait for session reset (usually 5 minutes)
+# Or use a different provider
+
+# Use provider fallback
+crewx query "@flexible_agent your question"
+# Where flexible_agent has: provider: ["claude", "gemini", "copilot"]
+```
+
+## Execution Issues
+
+### Agent Execution Fails
+
+**Problem:** Agent tasks fail or timeout
+
+**Diagnostics:**
+```bash
+# Run doctor
+crewx doctor
+
+# Check task logs
+crewx logs <task-id>
+
+# Verify agent configuration
+cat crewx.yaml
+```
+
+**Common causes:**
+1. Working directory doesn't exist
+2. Incorrect provider options
+3. Timeout too short for complex tasks
+4. Provider session limit
+5. **Cross-platform path issues** (hardcoded OS-specific paths)
+
+**Solutions:**
+```yaml
+# Fix working directory
+working_directory: "./src"  # Ensure path exists
+
+# Adjust timeout
+CODECREW_TIMEOUT_CLAUDE_EXECUTE=120000 crewx execute "@claude task"
+
+# Use provider fallback
+provider: ["claude", "gemini", "copilot"]
+```
+
+### Cross-Platform Path Issues
+
+**Problem:** Agent fails with `ENOENT` error on different operating systems
+
+**Cause:** Hardcoded absolute paths in `crewx.yaml` that only work on specific OS
+
+**Example error:**
+```
+ERROR: Process error: spawn C:\WINDOWS\system32\cmd.exe ENOENT
+```
+
+**Bad configuration (OS-specific):**
+```yaml
+agents:
+  - id: "my_agent"
+    working_directory: "/Users/username/project"  # ✗ macOS only
+    # or
+    working_directory: "C:\\Users\\username\\project"  # ✗ Windows only
+```
+
+**Good configuration (cross-platform):**
+```yaml
+agents:
+  - id: "my_agent"
+    # Option 1: Use relative path (recommended)
+    working_directory: "."
+
+    # Option 2: Omit working_directory (uses current directory)
+    # working_directory not specified = current directory
+
+    # Option 3: Use environment variable
+    working_directory: "${PROJECT_ROOT}/src"
+```
+
+**Quick fix:**
+1. Edit `crewx.yaml`
+2. Change absolute paths to relative paths (`.`, `./src`, etc.)
+3. Or remove `working_directory` entirely to use current directory
+4. Test: `crewx query "@agent hello"`
+
+**Debugging:**
+```bash
+# Check agent configuration
+cat crewx.yaml | grep -A 3 "working_directory"
+
+# Test agent
+crewx query "@agent test query"
+
+# Check logs for path errors
+cat .crewx/logs/*.log | grep -i "enoent\|working"
+```
+
+### Timeout Errors
+
+**Problem:** Tasks timeout before completion
+
+**Solution:**
+```bash
+# Increase timeout via environment variables
+export CODECREW_TIMEOUT_CLAUDE_QUERY=1800000  # 30 min
+export CODECREW_TIMEOUT_GEMINI_EXECUTE=2400000  # 40 min
+
+# Or inline
+CODECREW_TIMEOUT_CLAUDE_QUERY=1800000 crewx query "@claude complex task"
+```
+
+**Available timeout variables:**
+```bash
+CODECREW_TIMEOUT_CLAUDE_QUERY=600000
+CODECREW_TIMEOUT_CLAUDE_EXECUTE=45000
+CODECREW_TIMEOUT_GEMINI_QUERY=600000
+CODECREW_TIMEOUT_GEMINI_EXECUTE=1200000
+CODECREW_TIMEOUT_COPILOT_QUERY=600000
+CODECREW_TIMEOUT_COPILOT_EXECUTE=1200000
+CODECREW_TIMEOUT_PARALLEL=300000
+```
+
+### Pipeline Failures
+
+**Problem:** Piped commands fail or lose context
+
+**Solution:**
+```bash
+# Ensure each stage completes successfully
+crewx query "@claude design" && \
+crewx execute "@gemini implement"
+
+# Check pipeline output
+crewx query "@claude design" | tee design.txt | \
+crewx execute "@gemini implement"
+
+# Use thread for context instead
+crewx query "@claude design" --thread "project"
+crewx execute "@gemini implement" --thread "project"
+```
+
+## Thread/Conversation Issues
+
+### Thread Not Found
+
+**Problem:** `Error: Thread not found`
+
+**Solution:**
+```bash
+# Check existing threads
+ls .crewx/conversations/
+
+# Create new thread
+crewx query "@claude start" --thread "new-thread"
+
+# Thread names are case-sensitive
+crewx query "@claude continue" --thread "auth-feature"  # Correct
+crewx query "@claude continue" --thread "Auth-Feature"  # Different thread
+```
+
+### Context Not Preserved
+
+**Problem:** Agent doesn't remember previous conversation
+
+**Solution:**
+```bash
+# Ensure using same thread name
+crewx query "@claude design" --thread "myproject"
+crewx query "@claude refine" --thread "myproject"  # Same name
+
+# Check thread file exists
+cat .crewx/conversations/myproject.json
+
+# Thread is agent-specific
+crewx query "@claude talk" --thread "chat"     # Claude's thread
+crewx query "@gemini talk" --thread "chat"     # Different (Gemini's thread)
+```
+
+## Slack Integration Issues
+
+### Slack Bot Not Responding
+
+**Problem:** Bot doesn't respond to messages
+
+**Checklist:**
+1. Verify environment variables in `.env.slack`
+2. Check bot token permissions (chat:write, app_mentions:read, etc.)
+3. Ensure bot is invited to channel
+4. Check socket mode is enabled
+
+**Solution:**
+```bash
+# Verify .env.slack
+cat .env.slack
+
+# Required variables:
+# SLACK_BOT_TOKEN=xoxb-...
+# SLACK_APP_TOKEN=xapp-...
+# SLACK_SIGNING_SECRET=...
+
+# Restart bot
+npm run start:slack
+```
+
+### Slack Message Too Large
+
+**Problem:** `invalid_blocks` error
+
+**Solution:**
+```bash
+# Reduce max response length
+echo "SLACK_MAX_RESPONSE_LENGTH=200000" >> .env.slack
+
+# Restart bot
+npm run start:slack
+```
+
+## Performance Issues
+
+### Slow Responses
+
+**Problem:** Queries take too long to respond
+
+**Optimization:**
+```bash
+# Use faster models
+crewx query "@claude:haiku quick question"
+crewx query "@gemini:gemini-2.5-flash fast task"
+
+# Reduce context size
+# In crewx.yaml, limit --add-dir scope
+options:
+  query:
+    - "--add-dir=./src/specific-module"  # Instead of "."
+
+# Use parallel execution
+crewx query "@claude task1" "@gemini task2"  # Parallel
+```
+
+### High Memory Usage
+
+**Problem:** CrewX consuming too much memory
+
+**Solution:**
+```bash
+# Use lazy loading for documents
+# In documents.yaml:
+documents:
+  large-doc:
+    path: "docs/large.md"
+    lazy: true  # Only load when needed
+
+# Limit conversation history
+# Delete old threads
+rm .crewx/conversations/old-thread.json
+
+# Clear old logs
+crewx clear-logs
+```
+
+## Debugging
+
+### Enable Debug Logging
+
+```bash
+# Set debug environment variable
+export DEBUG=crewx:*
+
+# Run with verbose output
+crewx query "@claude test" --verbose
+
+# Check logs
+cat .crewx/logs/*.log
+```
+
+### Check System Status
+
+```bash
+# Comprehensive health check
+crewx doctor
+
+# Check provider availability
+crewx query "@claude hello"
+crewx query "@gemini hello"
+crewx query "@copilot hello"
+
+# Verify configuration
+cat agents.yaml
+```
+
+### Get Task Logs
+
+```bash
+# View specific task
+crewx logs <task-id>
+
+# View all recent tasks
+crewx logs
+
+# Find task ID from previous output
+# Look for: "Task ID: abc123"
+```
+
+## Getting Help
+
+If issues persist:
+
+1. **Run diagnostics:**
+   ```bash
+   crewx doctor
+   ```
+
+2. **Check logs:**
+   ```bash
+   ls .crewx/logs/
+   cat .crewx/logs/latest.log
+   ```
+
+3. **Verify configuration:**
+   ```bash
+   cat crewx.yaml  # or agents.yaml
+   crewx init --force  # Reset to defaults
+   ```
+
+4. **Test providers individually:**
+   ```bash
+   claude "hello"
+   gemini -p "hello"
+   gh copilot suggest "hello"
+   ```
+
+5. **Report issue:**
+   - GitHub: https://github.com/sowonlabs/crewx/issues
+   - Include: Error message, `crewx doctor` output, logs
+
+## Common Error Messages
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `crewx.yaml not found` | Missing configuration | Run `crewx init` |
+| `Provider not available` | CLI tool not installed | Install provider CLI |
+| `Session limit reached` | Too many requests | Wait or use different provider |
+| `Timeout exceeded` | Task too complex | Increase timeout via env vars |
+| `Invalid YAML syntax` | Malformed config | Run `crewx doctor` |
+| `Thread not found` | Wrong thread name | Check `.crewx/conversations/` |
+| `Permission denied` | File/directory access | Check working directory permissions |

package/package.json

@@ -1,26 +1,115 @@
 {
   "name": "crewx",
-  "version": "0.1.1",
-  "description": "Execute AI crews instantly without installation - Part of CrewCode AI Agent Platform",
-  "main": "index.js",
+  "version": "0.1.2",
+  "license": "Apache-2.0",
+  "description": "Bring Your Own AI(BYOA) team in Slack/IDE(MCP) with your existing subscriptions",
+  "main": "dist/main.js",
+  "module": "dist/main.js",
   "bin": {
-    "crewx": "./bin/crewx.js"
+    "crewx": "dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/main.js",
+      "require": "./dist/main.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "crewx.yaml",
+    "docs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sowonlabs/crewx"
+  },
+  "homepage": "https://github.com/sowonlabs/crewx",
+  "bugs": {
+    "url": "https://github.com/sowonlabs/crewx/issues"
+  },
+  "author": "SowonLabs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "nest build",
+    "postbuild": "node -e \"const fs = require('fs'); let content = fs.readFileSync('dist/main.js', 'utf8'); const lines = content.split('\\n'); if (lines[0] === '#!/usr/bin/env node' && lines[1] === '#!/usr/bin/env node') { lines.shift(); content = lines.join('\\n'); fs.writeFileSync('dist/main.js', content); console.log('✅ Removed duplicate shebang'); } else if (!content.startsWith('#!/usr/bin/env node')) { fs.writeFileSync('dist/main.js', '#!/usr/bin/env node\\n' + content); console.log('✅ Added shebang to dist/main.js'); } else { console.log('✅ Shebang already present'); }\"",
+    "build:install": "npm run build && npm install -g .",
+    "start": "node dist/main.js",
+    "start:mcp": "node dist/main.js mcp",
+    "start:slack": "caffeinate -i dotenv -e .env.slack -- node dist/main.js slack --log --agent crewx_dev",
+    "dev": "dotenv -e .env.test -- nest start --watch -- --log",
+    "dev:install": "ts-node src/main.ts --install --log",
+    "debug": "dotenv -e .env.test -- nest start --debug --watch -- --log --protocol HTTP",
+    "inspector": "npx @modelcontextprotocol/inspector --config inspector.config.json --server crewx",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "cli": "npm run build && node dist/main.js",
+    "cli:help": "npm run build && node dist/main.js",
+    "cli:init": "npm run build && node dist/main.js init",
+    "cli:doctor": "npm run build && node dist/main.js doctor",
+    "cli:query": "npm run build && node dist/main.js query",
+    "cli:execute": "npm run build && node dist/main.js execute",
+    "mcp": "npm run build && node dist/main.js mcp",
+    "mcp:log": "npm run build && node dist/main.js mcp --log",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "@slack/bolt": "^4.4.0",
+    "@slack/web-api": "^7.10.0",
+    "@sowonai/nestjs-mcp-adapter": "^0.1.3",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mdast": "^4.0.4",
+    "@types/unist": "^3.0.3",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "chalk": "^4.1.2",
+    "execa": "^8.0.1",
+    "fast-glob": "^3.3.0",
+    "handlebars": "^4.7.8",
+    "ignore": "^5.2.0",
+    "js-yaml": "^4.1.0",
+    "md-to-slack": "^1.0.0",
+    "reflect-metadata": "^0.1.13",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "rxjs": "^7.8.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0",
+    "yargs": "^17.7.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/ajv": "^0.0.5",
+    "@types/express": "^5.0.3",
+    "@types/node": "^20.19.19",
+    "@types/yargs": "^17.0.0",
+    "@vitest/ui": "^1.0.0",
+    "dotenv-cli": "^6.0.0",
+    "ts-loader": "^9.0.0",
+    "ts-node": "^10.0.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
   },
   "keywords": [
+    "crewx",
+    "claude",
+    "gemini",
+    "copilot",
+    "mcp",
     "ai",
-    "agents",
-    "crew",
-    "ai-agents",
-    "llm",
-    "development",
-    "automation",
-    "crewcode"
-  ],
-  "author": "Doha Park <dohapark81@gmail.com>",
-  "license": "UNLICENSED",
-  "private": false,
-  "homepage": "https://crewcode.dev",
-  "engines": {
-    "node": ">=18.0.0"
-  }
+    "model-context-protocol",
+    "multi-agent",
+    "ai-collaboration"
+  ]
 }