feat: Add intelligent auto-router and enhanced integrations
- Add intelligent-router.sh hook for automatic agent routing - Add AUTO-TRIGGER-SUMMARY.md documentation - Add FINAL-INTEGRATION-SUMMARY.md documentation - Complete Prometheus integration (6 commands + 4 tools) - Complete Dexto integration (12 commands + 5 tools) - Enhanced Ralph with access to all agents - Fix /clawd command (removed disable-model-invocation) - Update hooks.json to v5 with intelligent routing - 291 total skills now available - All 21 commands with automatic routing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
admin
337
dexto/DEVELOPMENT.md
Normal file
337
dexto/DEVELOPMENT.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# Development Guide
|
||||
|
||||
This guide covers development workflows for working on the Dexto codebase.
|
||||
|
||||
## Table of Contents
|
||||
- [Project Structure](#project-structure)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Development Workflows](#development-workflows)
|
||||
- [Build Commands](#build-commands)
|
||||
- [Testing](#testing)
|
||||
- [Code Quality](#code-quality)
|
||||
- [Publishing](#publishing)
|
||||
|
||||
## Project Structure
|
||||
|
||||
Dexto is a monorepo using pnpm workspaces with the following structure:
|
||||
|
||||
```
|
||||
dexto/
|
||||
├── packages/
|
||||
│ ├── core/ # @dexto/core - Core business logic
|
||||
│ ├── cli/ # dexto - CLI application
|
||||
│ └── webui/ # @dexto/webui - Next.js web interface
|
||||
├── scripts/ # Build and development scripts
|
||||
├── agents/ # Agent configurations
|
||||
└── docs/ # Documentation
|
||||
```
|
||||
|
||||
### Package Dependencies
|
||||
- `dexto` (CLI) depends on `@dexto/core`
|
||||
- `@dexto/webui` is embedded into CLI at build time
|
||||
- All packages version together (fixed versioning)
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
- Node.js >= 20.0.0
|
||||
- pnpm (automatically managed via Corepack)
|
||||
|
||||
### Initial Setup
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/truffle-ai/dexto.git
|
||||
cd dexto
|
||||
|
||||
# Enable Corepack (if not already enabled) - this picks pnpm version
|
||||
corepack enable
|
||||
|
||||
# Install dependencies (Corepack will use the correct pnpm version)
|
||||
pnpm install
|
||||
|
||||
# Build all packages
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
## Development Workflows
|
||||
|
||||
### 1. Hot Reload Development (Recommended)
|
||||
Best for frontend development with automatic reload:
|
||||
|
||||
```bash
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
This command:
|
||||
- Builds core and CLI packages
|
||||
- Runs API server on port 3001 (from built dist)
|
||||
- Runs WebUI dev server on port 3000 (with hot reload)
|
||||
- Prefixes output with `[API]` and `[UI]` for clarity
|
||||
- **Automatically sets `DEXTO_DEV_MODE=true`** to use repository agent configs
|
||||
|
||||
Access:
|
||||
- API: http://localhost:3001
|
||||
- WebUI: http://localhost:3000
|
||||
|
||||
### 2. Symlink Development
|
||||
Best for CLI development with instant changes:
|
||||
|
||||
```bash
|
||||
# Create global symlink (full build with WebUI)
|
||||
pnpm run link-cli
|
||||
|
||||
# Create global symlink (fast, no WebUI)
|
||||
pnpm run link-cli-fast
|
||||
|
||||
# Remove symlink
|
||||
pnpm run unlink-cli
|
||||
```
|
||||
|
||||
Now `dexto` command uses your local development code directly.
|
||||
|
||||
### 3. Production-like Testing
|
||||
Test the actual installation experience:
|
||||
|
||||
```bash
|
||||
# Install globally from local build (full)
|
||||
pnpm run install-cli
|
||||
|
||||
# Install globally from local build (fast, no WebUI)
|
||||
pnpm run install-cli-fast
|
||||
```
|
||||
|
||||
This creates tarballs and installs them globally, simulating `npm install -g dexto`.
|
||||
|
||||
### Switching Between Workflows
|
||||
|
||||
The `link-cli` and `install-cli` commands are mutually exclusive:
|
||||
- Running `link-cli` removes any npm installation
|
||||
- Running `install-cli` removes any pnpm symlink
|
||||
- Use `unlink-cli` to remove everything
|
||||
|
||||
## Build Commands
|
||||
|
||||
### Complete Builds
|
||||
```bash
|
||||
# Full build with cleaning
|
||||
pnpm run build
|
||||
|
||||
# Build all packages without cleaning
|
||||
pnpm run build:all
|
||||
|
||||
# Build with type checking
|
||||
pnpm run build:check
|
||||
```
|
||||
|
||||
### Package-Specific Builds
|
||||
```bash
|
||||
# Build individual packages
|
||||
pnpm run build:core
|
||||
pnpm run build:cli
|
||||
pnpm run build:webui
|
||||
|
||||
# Build CLI and its dependencies only (no WebUI)
|
||||
pnpm run build:cli-only
|
||||
```
|
||||
|
||||
### WebUI Embedding
|
||||
The WebUI is embedded into the CLI's dist folder during build:
|
||||
|
||||
```bash
|
||||
# Embed WebUI into CLI dist (run after building WebUI)
|
||||
pnpm run embed-webui
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Automated Tests
|
||||
```bash
|
||||
# Run all tests
|
||||
pnpm test
|
||||
|
||||
# Run unit tests only
|
||||
pnpm run test:unit
|
||||
|
||||
# Run integration tests only
|
||||
pnpm run test:integ
|
||||
|
||||
# Run tests with coverage
|
||||
pnpm run test:ci
|
||||
```
|
||||
|
||||
### Manual testing
|
||||
|
||||
1. Common commands
|
||||
```bash
|
||||
cd ~
|
||||
dexto --help
|
||||
dexto "what is the current time"
|
||||
dexto "list files in current directory"
|
||||
|
||||
# Test other model override in CLI
|
||||
dexto -m gpt-5-mini "what is the current date"
|
||||
|
||||
# Test web mode
|
||||
dexto
|
||||
|
||||
# Test discord bot mode (requires additional setup)
|
||||
dexto --mode discord
|
||||
|
||||
# Test telegram bot mode (requires additional setup)
|
||||
dexto --mode telegram
|
||||
```
|
||||
|
||||
2. Execution contexts
|
||||
|
||||
Dexto CLI operates differently based on the directory you are running in.
|
||||
- source context -> when Dexto CLI is run in the source repository
|
||||
- global context -> when Dexto CLI is run outside the source repository
|
||||
- project context -> when Dexto CLI is run in a project that consumes @dexto dependencies
|
||||
|
||||
Based on execution context, Dexto CLI will use defaults for log path, default agent/agent registry.
|
||||
Run the CLI in different places and see the console logs to understand this.
|
||||
|
||||
Test above commands in different execution contexts for manual testing coverage.
|
||||
|
||||
**Developer Mode Environment Variable:**
|
||||
|
||||
When running `dexto` from within this repository, it normally uses your `dexto setup` preferences and global `~/.dexto` directory. To force isolated testing with repository files:
|
||||
```bash
|
||||
export DEXTO_DEV_MODE=true # Use repo configs and local .dexto directory
|
||||
```
|
||||
|
||||
**DEXTO_DEV_MODE Behavior:**
|
||||
- **Agent Config**: Uses `agents/coding-agent/coding-agent.yml` from repo (instead of `~/.dexto/agents/`)
|
||||
- **Logs/Database**: Uses `repo/.dexto/` (instead of `~/.dexto/`)
|
||||
- **Preferences**: Skips global setup validation
|
||||
- **Use Case**: Isolated testing and development on Dexto itself
|
||||
|
||||
**Note**: `pnpm run dev` automatically sets `DEXTO_DEV_MODE=true`, so the development server always uses repository configs and local storage.
|
||||
|
||||
## Code Quality
|
||||
|
||||
### Type Checking
|
||||
```bash
|
||||
# Type check all packages
|
||||
pnpm run typecheck
|
||||
|
||||
# Type check with file watching
|
||||
pnpm run typecheck:watch
|
||||
|
||||
# Type check specific package
|
||||
pnpm run typecheck:core
|
||||
```
|
||||
|
||||
### Linting
|
||||
```bash
|
||||
# Run linter
|
||||
pnpm run lint
|
||||
|
||||
# Fix linting issues
|
||||
pnpm run lint:fix
|
||||
```
|
||||
|
||||
### Pre-commit Checks
|
||||
Before committing, always run:
|
||||
```bash
|
||||
pnpm run build:check # Typecheck + build
|
||||
pnpm test # Run tests
|
||||
pnpm run lint # Check linting
|
||||
```
|
||||
|
||||
## Publishing
|
||||
|
||||
### Changeset Workflow
|
||||
|
||||
We use [Changesets](https://github.com/changesets/changesets) for version management:
|
||||
|
||||
1. **Create a changeset** for your changes:
|
||||
```bash
|
||||
pnpm changeset
|
||||
```
|
||||
|
||||
2. **Select packages** affected by your change
|
||||
|
||||
3. **Choose version bump** (patch/minor/major)
|
||||
|
||||
4. **Write summary** of your changes
|
||||
|
||||
### Version Strategy
|
||||
|
||||
- **Fixed versioning**: All packages version together
|
||||
- `@dexto/core` and `dexto` always have the same version
|
||||
- `@dexto/webui` is private and not published
|
||||
|
||||
### Publishing Process
|
||||
|
||||
Publishing is automated via GitHub Actions:
|
||||
1. Merge PR with changeset
|
||||
2. Bot creates "Version Packages" PR
|
||||
3. Merge version PR to trigger npm publish
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Clean Everything
|
||||
```bash
|
||||
# Clean all build artifacts and caches
|
||||
pnpm run clean
|
||||
|
||||
# Clean storage only
|
||||
pnpm run clean:storage
|
||||
```
|
||||
|
||||
### Start Production Server
|
||||
```bash
|
||||
# Start the CLI (requires build first)
|
||||
pnpm start
|
||||
```
|
||||
|
||||
### Working with Turbo
|
||||
|
||||
Turbo commands run tasks across all packages:
|
||||
```bash
|
||||
pnpm run repo:build # Build all packages with Turbo
|
||||
pnpm run repo:test # Test all packages with Turbo
|
||||
pnpm run repo:lint # Lint all packages with Turbo
|
||||
pnpm run repo:typecheck # Typecheck all packages with Turbo
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Native Dependencies
|
||||
If you see errors about missing bindings (e.g., better-sqlite3):
|
||||
```bash
|
||||
# Reinstall dependencies
|
||||
pnpm install
|
||||
|
||||
# If that doesn't work, clean and reinstall
|
||||
pnpm run clean
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### Port Conflicts
|
||||
Default ports:
|
||||
- API/Server: 3001
|
||||
- WebUI Dev: 3000
|
||||
|
||||
Set environment variables to use different ports:
|
||||
```bash
|
||||
PORT=4000 API_PORT=4001 pnpm run dev
|
||||
```
|
||||
|
||||
### Global Command Not Found
|
||||
If `dexto` command is not found after linking:
|
||||
```bash
|
||||
# Check global installations
|
||||
pnpm list -g
|
||||
npm list -g dexto --depth=0
|
||||
|
||||
# Verify PATH includes pnpm/npm global bin
|
||||
echo $PATH
|
||||
```
|
||||
|
||||
## Questions?
|
||||
|
||||
- Check [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines
|
||||
- Open an issue for bugs or feature requests
|
||||
- Join our Discord for development discussions
|
||||
Reference in New Issue
Block a user