@graphteon/juricode/README.md

We are forging the future with lines of digital steel

# Juricode CLI

We are forging the future with lines of digital steel

A CLI version of the OpenHands frontend, providing command-line access to OpenHands functionality.

## Installation

```bash
npm install -g @graphteon/juricode
```

## Usage

```bash
juricode --help
```

## Features

- **SSH Tunneling**: Automatic SSH tunnel setup for remote OpenHands instances
- **VSCode Integration**: `/editor` command for direct VSCode access through SSH tunnels
- **Suggested Tasks**: Browse and start working on AI-suggested tasks from your repositories
- **Multi-Provider Support**: GitHub, GitLab, and Bitbucket integration
- **Enhanced Performance**: Optimized React rendering and smooth typing experience
- **Smart Pagination**: 20-item windowed display for large lists
- **Clean UI**: Filtered system messages and duplicate prevention
- **Modern API**: Updated to match OpenHands frontend v0.45.0
- **CLI Interface**: Full command-line access to OpenHands features

## Recent Updates (v0.3.0)

### Major New Features
- **SSH Tunneling System**: Automatic SSH connection and port forwarding to remote OpenHands instances
- **VSCode Integration**: `/editor` command opens VSCode through SSH tunnels for seamless remote development
- **Enhanced Performance**: Fixed typing glitches and optimized React rendering with memoization
- **Smart UI Improvements**: 20-item pagination, duplicate message prevention, and system message filtering

### Technical Improvements
- **SSH Library Migration**: Replaced `node-ssh` with `ssh2` for better tunneling control
- **React Optimization**: Implemented `useMemo`, `useCallback`, and `React.memo` for smooth performance
- **Message Deduplication**: Unique ID tracking prevents duplicate messages in conversations
- **Reliable Exit**: Enhanced exit functionality with `process.exit(0)` and proper cleanup
- **WebSocket Management**: Improved connection lifecycle and state management

### Bug Fixes
- Fixed conversation typing glitches and re-rendering issues
- Resolved duplicate messages when loading existing conversations
- Enhanced exit handling for reliable application termination
- Improved SSH authentication flow with proper async handling
- Fixed layout issues in repositories and suggested tasks views

### Previous Updates (v0.2.0)
- **Suggested Tasks Menu**: Browse failing checks, merge conflicts, and open issues
- Added Bitbucket provider support
- Enhanced settings with budget management (`MAX_BUDGET_PER_TASK`)
- Email verification support (`EMAIL`, `EMAIL_VERIFIED`)
- Updated API client to match OpenHands frontend structure
- Improved TypeScript configuration with DOM support

## Development

```bash
npm install
npm run build
```

### Build Scripts
- `npm run build:esm` - Build ES modules
- `npm run build:cjs` - Build CommonJS modules
- `npm run build:types` - Generate TypeScript declarations
- `npm run build` - Build all formats

## Usage Guide

### Main Menu Options

1. **📋 View All Tasks** - Browse existing conversations and tasks
2. **💡 Suggested Tasks** - Browse AI-suggested tasks from your repositories
   - Failing CI/CD checks that need attention
   - Merge conflicts requiring resolution
   - Open issues ready for development
3. **📚 Browse Repositories** - Explore your connected repositories
4. **📝 Create New Task** - Start a new conversation/task manually

### SSH Tunneling & VSCode Integration

JuriCode now includes automatic SSH tunneling for seamless remote development:

1. **Automatic SSH Setup**: Connects to `ubuntu@aigw.biznetgio.dev` and forwards port 3000
2. **VSCode Integration**: Use `/editor` command in any conversation to open VSCode
3. **Seamless Development**: Work on remote OpenHands instances as if they were local

### Special Commands in Conversations

- **`/editor`**: Opens VSCode through SSH tunnel for direct code editing
- **`exit`**: Cleanly exits the conversation and returns to main menu

### Suggested Tasks Workflow

1. Select "💡 Suggested Tasks" from main menu
2. Browse categorized tasks (20 items per page):
   - ❌ **FAILING_CHECKS** - CI/CD failures needing fixes
   - 🔀 **MERGE_CONFLICTS** - Pull requests with conflicts
   - 📋 **OPEN_ISSUE** - Issues ready for development
3. Select a task to view details
4. Choose "🚀 Start Working on Task" to create a conversation
5. Use `/editor` command for direct code editing when needed
6. Optionally start an immediate chat session with the AI

## Configuration

### Environment Variables

Set the OpenHands base URL:
```bash
export JURICODE_BASE_URL=http://localhost:3000
```

For websocket connections (if different from base URL):
```bash
export JURICODE_WS_URL=http://localhost:3000
```

Set connection timeout (default: 10000ms):
```bash
export JURICODE_TIMEOUT=15000
```

### SSH Tunneling Configuration

JuriCode includes built-in SSH tunneling that automatically connects to remote OpenHands instances:

**Default SSH Configuration:**
- Host: `ubuntu@aigw.biznetgio.dev`
- Port forwarding: Remote port 3000 → Local port 3000
- Authentication: SSH key-based (uses your default SSH key)

**Manual SSH Setup (if needed):**
```bash
# Manual SSH tunnel (JuriCode does this automatically)
ssh -L 3000:localhost:3000 ubuntu@aigw.biznetgio.dev

# Then run juricode
export JURICODE_BASE_URL=http://localhost:3000
juricode
```

### Troubleshooting

**SSH Connection Issues:**
1. **SSH Key Setup**: Ensure your SSH key is added to the remote server
2. **Network Access**: Verify you can reach `aigw.biznetgio.dev`
3. **Port Conflicts**: Check if local port 3000 is already in use

**WebSocket Connection Issues:**
1. **Check OpenHands Backend**: Ensure OpenHands backend is running on remote server
2. **Verify URL**: Make sure `JURICODE_BASE_URL` points to `http://localhost:3000`
3. **SSH Tunnel**: Verify SSH tunnel is active and forwarding port 3000
4. **Firewall**: Check if firewall is blocking SSH or local port access

**VSCode Integration Issues:**
1. **SSH Tunnel**: Ensure SSH tunnel is established before using `/editor`
2. **VSCode Installation**: Verify VSCode is installed and accessible via `code` command
3. **Remote Access**: Check that VSCode can connect through the SSH tunnel

## Configuration Examples

**Standard Usage (with built-in SSH tunneling):**
```bash
# JuriCode automatically sets up SSH tunnel to aigw.biznetgio.dev
export JURICODE_BASE_URL=http://localhost:3000
juricode
```

**Local Development:**
```bash
# For local OpenHands instance
export JURICODE_BASE_URL=http://localhost:3000
juricode
```

**Custom Remote Server:**
```bash
# Manual SSH tunnel to custom server
ssh -L 3000:localhost:3000 user@your-remote-host
export JURICODE_BASE_URL=http://localhost:3000
juricode
```

**VSCode Integration:**
```bash
# After starting juricode, use /editor command in any conversation
# This automatically opens VSCode through the SSH tunnel
```

## License

MIT

## Contributing

This project is synchronized with the OpenHands frontend. When updating, ensure compatibility with the latest OpenHands release.