@naarang/ccc 1.2.0-beta.9 → 2.0.0-alpha.1

package/README.md

@@ -1,569 +1,136 @@
-# CCC - UI Interface for Coding Agents like Claude Code
-
-**Control Claude Code and other coding agents from your mobile device**
-
-CCC is a powerful CLI tool that creates a bridge between [Claude Code](https://claude.com/claude-code) and your mobile device, allowing you to chat with Claude and execute code operations remotely through a mobile app.
-
-[![npm version](https://img.shields.io/npm/v/@naarang/ccc.svg?style=flat-square)](https://www.npmjs.com/package/@naarang/ccc)
-[![Node Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen?style=flat-square)](https://nodejs.org)
-
-![CCC Terminal Screenshot](https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/carbon%20(1).png?alt=media&token=1541cc51-0a24-4055-b73f-81e181217f53)
-
-<p align="center">
-  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/Projects.jpg?alt=media&token=098ed213-ed4a-4e22-9447-4cd097e9f485" width="150" />
-  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/context.jpg?alt=media&token=4acc826e-544d-44d4-bfee-3dc716023600" width="150" />
-  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/permissions.jpg?alt=media&token=1af2c554-e2be-49e6-bb80-620d7e3f4ecd" width="150" />
-  <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/thinking.jpg?alt=media&token=04e4dff7-78a7-4e6c-ac08-bc3371889b07" width="150" />
-</p>
-
-<p align="center">
-  <a href="https://play.google.com/store/apps/details?id=com.naarang.ccc">
-    <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/GetItOnGooglePlay_Badge_Web_color_English.png?alt=media&token=d2f34558-ce96-4882-9225-8ded76f759ba" alt="Get it on Google Play" height="80">
-  </a>
-  <br/>
-  <a href="https://play.google.com/apps/testing/com.naarang.ccc">
-    <sub>Join Android Beta Testing</sub>
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://apps.apple.com/in/app/ccc-ui-for-coding-agents/id6753870766">
-    <img src="https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg" alt="Download on the App Store" height="80">
-  </a>
-  <br/>
-  <a href="https://testflight.apple.com/join/bEVNMrNH">
-    <sub>Join iOS Beta Testing (TestFlight)</sub>
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://discord.gg/9EjE8t4YCF">
-    <img src="https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord">
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://getc3.app/support">
-    <img src="https://img.shields.io/badge/Support-CCC-blue?style=for-the-badge" alt="Support CCC">
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://getc3.app">
-    <img src="https://img.shields.io/badge/Website-getc3.app-green?style=for-the-badge" alt="Visit Website">
-  </a>
-</p>
-
-## ✨ Features
-
-- **Mobile Control** - Chat with Claude from your phone or tablet
-- **Real-time Sync** - See Claude's responses instantly on your device
-- **Smart Permission System** - Fine-grained control over code modifications
-- **Web Terminal Access** 🆕 (Beta) - Full terminal access with auto-generated secure credentials
-- **Request Cancellation** 🆕 - Abort ongoing Claude requests from mobile app
-- **Dynamic Project Switching** 🆕 - Terminal automatically changes directory when switching projects
-- **Remote Access** - Optional ngrok integration for access from anywhere
-- **Secure MQTT** - Built-in MQTT broker with authentication support (required for ngrok)
-- **Session Management** - Persistent sessions across reconnections
-- **Context Awareness** - Full project context and file system access
-- **Auto Hook Setup** - Automatic project configuration for permission handling
-- **Auto-Update System** 🆕 - Automatic version checks and updates (can be disabled)
-
-## Installation
-
-### Global Installation (Recommended)
-
-```bash
-npm install -g @naarang/ccc
-```
-
-### Local Installation
-
-```bash
-npm install @naarang/ccc
-npx ccc
-```
-
-### Windows Installation
-
-CCC requires native modules (node-pty) for terminal functionality. On Windows, you need to install build tools first:
-
-**Option 1: Windows Build Tools (Recommended)**
-```bash
-npm install -g windows-build-tools
-npm install -g @naarang/ccc
-```
-
-**Option 2: Visual Studio Build Tools**
-1. Download [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/)
-2. Install with "Desktop development with C++" workload
-3. Run: `npm install -g @naarang/ccc`
-
-**If you encounter terminal errors after installation:**
-```bash
-# Navigate to the CCC installation directory
-cd %APPDATA%\npm\node_modules\@naarang\ccc
-
-# Rebuild node-pty
-npm rebuild node-pty
-```
-
-The postinstall script will automatically check if node-pty is working and provide guidance if there are issues.
-
-## Quick Start
-
-### 1. Start the Backend Server
-
-Simply run:
-
-```bash
-ccc
-```
-
-The server will start and display:
-```
-✓ Terminal server started on localhost:3001
-✓ Path router started on port 8883
-✓ Claude Chat Backend v1.1.x started successfully
- 
-Server URLs (Add one of these in the app settings):
-    Localhost: localhost:8883
-    Network:   192.168.1.135:8883
- 
-Services:
-    MQTT:      Port 8884 (via /mqtt)
-    Terminal:  Port 3001 (via /terminal) - Auto-secured
- 
-MQTT Auth: Enabled
-```
-
-### 2. Configure the Mobile App
-
-Download the CCC mobile app and add the server connection:
-
-**For Local Network:**
-```
-Server URL: 192.168.x.xxx:8883
-```
-
-**For Remote Access:**
-```bash
-ccc --ngrok-token YOUR_TOKEN
-```
-Use the provided ngrok URL in the app.
-
-### 3. Start Chatting
-
-Open the app, create a project pointing to your local directory, and start chatting with Claude!
-
-## ⚙️ Configuration
-
-### Command Line Options
-
-```bash
-ccc [options]
-
-Options:
-  --debug                           Enable debug logging
-  -u, --username <user>             MQTT broker username (required for ngrok)
-  -p, --password <pass>             MQTT broker password (required for ngrok)
-  --mqtt-port <port>                Internal MQTT broker port (default: 8884)
-  --port <port>                     [DEPRECATED] Use --mqtt-port instead
-  --router-port <port>              Internal Request Router port. This is what the app connects to (default: 8883)
-  --terminal-port <port>            Internal terminal server port (default: 3001)
-  -t, --ngrok-token <token>         ngrok auth token (enables public tunnel, requires MQTT auth)
-  --ngrok-domain <domain>           ngrok static domain
-  --no-auto-update                  Disable automatic updates (enabled by default)
-  -v, --version                     Show version number
-  -h, --help                        Show help message
-
-Note: Terminal credentials are automatically generated and cannot be configured manually.
-```
-
-> **Auto-Update**: By default, CCC checks for updates on startup and automatically downloads the latest version. After a successful update, you'll be prompted to manually restart the server. Use `--no-auto-update` to disable this behavior.
-
-### Examples
-
-**Basic usage:**
-```bash
-ccc
-```
-
-**With authentication:**
-```bash
-ccc -u admin -p secret
-```
-
-**With terminal access (Beta):**
-```bash
-# Terminal credentials are automatically generated
-# No configuration needed - just start the server
-ccc
-
-# Terminal credentials are broadcast to authorized clients via MQTT
-# App receives credentials automatically on connection
-```
-
-**With ngrok for remote access:**
-```bash
-ccc --ngrok-token YOUR_NGROK_TOKEN
-```
-
-**Full example with ngrok and authentication:**
-```bash
-# Terminal credentials auto-generated
-# MQTT authentication required for ngrok
-ccc --ngrok-token YOUR_TOKEN \
-    -u admin \
-    -p secret
-```
-
-**Custom ports with debug logging:**
-```bash
-ccc --mqtt-port 9000 --terminal-port 3002 --debug
-```
-
-## 🖥️ Terminal Access (Beta)
-
-CCC now includes a built-in web terminal that can be accessed directly from the mobile app. This feature is currently in **beta** and provides full terminal access to your development environment.
-
-### Security Model
-
-**Terminal credentials are automatically generated** for maximum security. The terminal server:
-- ✅ **Auto-generates strong credentials** on startup
-- ✅ **Always enabled** - no configuration needed
-- ✅ **Credentials shared securely** via MQTT to authorized clients only
-- ❌ **Not user-configurable** - prevents weak passwords
-- 🔄 **Auto-broadcast on connection** - clients receive credentials automatically
-
-**MQTT Authentication** is separate and optional:
-- ✅ **Optional for localhost** - no auth needed for local development
-- ⚠️ **Required for ngrok tunnels** - protects public endpoints (enforced at startup)
-
-### How It Works
-
-1. **Architecture:**
-   - Internal terminal server runs on port 3001 (localhost only)
-   - Proxied through the main router on `/terminal` path
-   - Full terminal emulation with bash/powershell support
-
-2. **Security Features:**
-   - Basic authentication required for all connections
-   - Rate limiting: max 5 failed auth attempts (15-minute IP block)
-   - Session limit: maximum 5 concurrent terminals
-   - Bound to localhost only (never exposed directly)
-   - All connections must go through authenticated router
-
-3. **Mobile Integration:**
-   - Terminal embedded in mobile app
-   - Auto-configures when credentials are provided
-   - **Automatic authentication** - App automatically authenticates with terminal (no manual login needed)
-   - **Dynamic path updates** - Terminal working directory changes automatically when switching projects via MQTT
-   - Starts in your project directory by default
-
-### Terminal Features
-
-- ✅ Full terminal emulation
-- ✅ Color support and ANSI escape sequences
-- ✅ Responsive design (works on mobile)
-- ✅ Multiple concurrent sessions (max 5)
-- ✅ Automatic resize on orientation change
-- ✅ Custom theme matching app design
-- ✅ Scrollback history
-- ✅ Auto-generated secure credentials (no manual configuration)
-- ✅ Project-aware (changes directory when you switch projects)
-
-### Usage from Mobile App
-
-Once enabled on the backend:
-1. Open CCC mobile app
-2. Navigate to the project
-3. Terminal icon will appear in the toolbar automatically
-4. Tap to open full-screen terminal
-5. Terminal opens directly in your project directory
-6. Use on-screen keyboard or external keyboard
-
-### Security Best Practices
-
-⚠️ **Important Security Notes:**
-
-1. **Terminal Credentials are Auto-Generated:** No weak passwords possible
-   - System generates 32-char username + 480-char password on startup
-   - Credentials automatically broadcast to authorized clients via MQTT
-   - Cannot be manually configured (prevents security mistakes)
-
-2. **Use MQTT Authentication for ngrok:** Required for remote access
-   ```bash
-   ccc --ngrok-token YOUR_TOKEN \
-       -u admin \
-       -p $(openssl rand -base64 32)
-   ```
-
-3. **Monitor Active Sessions:** Check logs for suspicious activity
-   ```bash
-   ccc --debug  # Enable detailed logging
-   ```
-
-4. **Restrict Network Access:** Only use on trusted networks or via ngrok
-   - Terminal bound to localhost only
-   - All access must go through authenticated router
-
-### Troubleshooting Terminal
-
-**Terminal won't connect:**
-- Check logs with `--debug` flag to see credential generation
-- Ensure port 3001 is not in use
-- Verify MQTT connection is established (terminal credentials sent via MQTT)
-- Check that app received terminal configuration (should happen automatically)
-
-**Windows: "Cannot find module '../build/Release/conpty.node'" error:**
-
-This means node-pty native modules weren't built properly. Fix it with:
-
-```bash
-# Option 1: Rebuild node-pty in place
-cd %APPDATA%\npm\node_modules\@naarang\ccc
-npm rebuild node-pty
-
-# Option 2: Reinstall CCC completely
-npm uninstall -g @naarang/ccc
-npm install -g windows-build-tools
-npm install -g @naarang/ccc
-
-# Option 3: If you have Visual Studio Build Tools installed
-npm uninstall -g @naarang/ccc
-npm install -g @naarang/ccc --build-from-source
-```
-
-If you still have issues, ensure you have:
-- Windows Build Tools: `npm install -g windows-build-tools`
-- Or Visual Studio with "Desktop development with C++" workload
-
-**Authentication failures:**
-- Check for IP blocking (max 5 failed attempts)
-- Wait 15 minutes if blocked
-- Restart server to clear blocks and regenerate credentials
-
-**Terminal not showing in app:**
-- Ensure server is running (credentials auto-generated on startup)
-- Verify MQTT connection is active
-- Check that app received system config via MQTT
-- Restart the mobile app to force credential refresh
-
-## Permission Modes
-
-CCC offers four permission modes to balance convenience and security:
-
-### 1. Default Mode (Recommended)
-- Prompts for approval on first use of each tool/command
-- Click "Yes, don't ask again" to add to allowed list
-- Granular control over specific commands
-- **Use case:** Balanced security and productivity
-
-### 2. Accept Edits Mode
-- Automatically approves file modifications (Edit, Write, NotebookEdit)
-- Still prompts for other operations (Read, Bash, WebFetch)
-- **Use case:** Active development sessions
-
-### 3. Plan Mode
-- Analysis only, no code changes without approval
-- Perfect for code review and exploration
-- **Use case:** Reviewing unfamiliar code
-
-### 4. Bypass All ⚠️
-- Skips all permission prompts
-- **Use with extreme caution!**
-- **Use case:** Controlled environments only
-
-### Project Structure
-
-CCC creates the following in your project:
-
-```
-your-project/
-├── .claude/
-│   ├── hooks/
-│   │   ├── permissions_hook.js  # Permission handling
-│   │   ├── package.json         # Hook dependencies
-│   │   └── .env                 # MQTT configuration
-│   ├── settings.local.json      # Hook registration & allowed tools
-│   ├── sessions.json            # Session mappings
-│   └── session-config.json      # Permission modes & backend version
-└── [your project files]
-```
-
-## Mobile App
-
-The CCC mobile app is required to interact with the backend.
-
-<p align="center">
-  <a href="https://play.google.com/store/apps/details?id=com.naarang.ccc">
-    <img src="https://firebasestorage.googleapis.com/v0/b/cc-chat-ui.firebasestorage.app/o/GetItOnGooglePlay_Badge_Web_color_English.png?alt=media&token=d2f34558-ce96-4882-9225-8ded76f759ba" alt="Get it on Google Play" height="80">
-  </a>
-  <br/>
-  <a href="https://play.google.com/apps/testing/com.naarang.ccc">
-    <sub>Join Android Beta Testing</sub>
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://apps.apple.com/in/app/ccc-ui-for-coding-agents/id6753870766">
-    <img src="https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg" alt="Download on the App Store" height="80">
-  </a>
-  <br/>
-  <a href="https://testflight.apple.com/join/bEVNMrNH">
-    <sub>Join iOS Beta Testing (TestFlight)</sub>
-  </a>
-</p>
-
-### Features
-- Multiple project management
-- Real-time chat interface
-- Permission request handling
-- Integrated web terminal (Beta) - auto-configured with secure credentials
-- Request cancellation - abort ongoing Claude operations
-- Dynamic project switching - terminal follows your active project
-- Image attachments support (PNG, JPEG, GIF, WebP - max 5MB each)
-- Server profile management
-- Connection health monitoring
-- Theme support (light/dark)
-
-### Connection Setup
-
-1. Open the mobile app
-2. Go to Settings → Add Server Profile
-3. Enter server URL
-4. Add credentials if authentication is enabled
-5. Create a project pointing to your code directory
-
-## Troubleshooting
-
-### Server Won't Start
-
-**Error: `EADDRINUSE: address already in use`**
-
-Another process is using the default ports. Find and kill the process, or use different ports:
-```bash
-# Find the process using router port (8883)
-lsof -i :8883
-
-# Or MQTT port (8884)
-lsof -i :8884
-
-# Kill it
-kill -9 <PID>
-
-# Or use different ports
-ccc --router-port 9000 --mqtt-port 9001
-```
-
-### Connection Issues
-
-**Mobile app can't connect:**
-
-**Checklist:**
-1. Check you're on the same WiFi network (for local)
-2. Verify server is running (`ccc` should show "started successfully")
-3. Check firewall settings allow port 8883 (router port that app connects to)
-4. Use correct format: `hostname:8883` (no `http://`)
-5. Enable debug mode: `ccc --debug`
-
-### Permission Hook Errors
-
-**Hooks not working:**
-
-1. Delete `.claude/` folder and restart server
-2. Check permissions on project directory
-3. Verify Node.js version >=18
-4. Check logs with `--debug` flag
-
-### Claude Not Responding
-
-**Common issues:**
-
-1. **Claude not installed:** Run `claude --version`
-2. **Not authenticated:** Run `claude auth status`
-3. **Invalid project path:** Check path exists and is accessible
-4. **API limits:** Check your Claude subscription status
-
-## Security Best Practices
-
-1. **Use Authentication**
-   ```bash
-   ccc -u admin -p $(openssl rand -base64 32)
-   ```
-
-2. **Limit Network Exposure**
-   - Use ngrok for remote access instead of port forwarding
-   - Enable firewall rules
-
-3. **Review Allowed Tools**
-   - Check `.claude/settings.local.json` regularly
-   - Remove unused permissions
-
-4. **Use Plan Mode**
-   - When reviewing unfamiliar code
-   - For read-only sessions
-
-5. **Keep Updated**
-   ```bash
-   npm update -g @naarang/ccc
-   ```
-
-## System Requirements
-
-- **Node.js**: v20.0.0 or higher
-- **Claude Code**: Latest version
-- **Claude Subscription**: Active Pro or Max account
-- **Operating Systems**:
-  - ✅ Linux (Ubuntu, Debian, Fedora)
-  - ✅ macOS (10.15+)
-  - ✅ Windows (via WSL2 recommended)
-- **Network**: WiFi or ethernet for mobile connection
-
-## Use Cases
-
-### Remote Development
-Work on code from your couch, bed, or anywhere with your mobile device.
-
-### Code Review
-Review and discuss code changes with Claude on the go.
-
-### Quick Fixes
-Make quick code changes without opening your laptop.
-
-### Learning
-Learn coding concepts by chatting with Claude from mobile.
-
-### Pair Programming
-Collaborate with Claude on coding tasks remotely.
-
-
-## Performance
-
-- **Startup Time**: ~2 seconds
-- **Response Latency**: <100ms (local network)
-- **Concurrent Sessions**: Unlimited
-- **Memory Usage**: ~150MB (varies with active sessions)
-
-## Support the Project
-
-If you find this project useful, consider supporting its development:
-
-[![Support](https://img.shields.io/badge/Support-CCC-blue?style=for-the-badge)](https://getc3.app/support)
-
-Visit [getc3.app/support](https://getc3.app/support) for donation options.
-
-## Support & Community
-
-- **Discord**: Join our community at https://discord.gg/9EjE8t4YCF
-- **Issues**: Report bugs and request features
-- **Discussions**: Ask questions and share ideas
-- **Updates**: Check npm for latest version
-- **Contact**: Email us at cccuiapp@gmail.com
-
-**Made with ❤️ by naarang**
-
-> **Note**: This tool requires an active Claude subscription and Claude Code to function properly.
-
-**Get Started:** `npm install -g @naarang/ccc && ccc`
+# CCC Backend v2 - Code Chat Connect
+
+A clean, modular backend for Code Chat Connect using Bun's native capabilities and modern service-oriented architecture.
+
+## Requirements
+
+**Bun runtime is required.** This package will not work with Node.js.
+
+Install Bun:
+```bash
+# Windows (PowerShell)
+powershell -c "irm bun.sh/install.ps1|iex"
+
+# macOS / Linux
+curl -fsSL https://bun.sh/install | bash
+```
+
+Learn more: https://bun.sh
+
+## Installation
+
+### Global Install (Recommended)
+
+```bash
+npm install -g @naarang/ccc
+```
+
+Then run:
+```bash
+ccc
+```
+
+### Local Development
+
+```bash
+bun install
+bun src/index.ts
+```
+
+## Usage
+
+```bash
+# Start with default settings
+ccc
+
+# Enable debug logging
+ccc --debug
+
+# With custom ports
+ccc --mqtt-port 8884 --router-port 8883 --terminal-port 3001
+
+# With MQTT authentication (required for ngrok)
+ccc --username myuser --password mypass
+
+# With ngrok tunnel for remote access
+ccc --username myuser --password mypass --ngrok-token YOUR_TOKEN
+```
+
+## CLI Options
+
+```
+-d, --debug                          Enable debug logging
+--mqtt-port <port>                   MQTT broker port (default: 8884)
+--terminal-port <port>               Terminal server port (default: 3001)
+--router-port <port>                 Router port (default: 8883)
+--username <username>                MQTT broker username (optional)
+--password <password>                MQTT broker password (optional)
+--ngrok-token <token>                ngrok auth token for remote access
+--ngrok-domain <domain>              ngrok static domain (paid plan)
+--no-auto-update                     Disable automatic updates
+-h, --help                           Show help message
+```
+
+## Services
+
+The backend provides these core services:
+
+1. **MQTT Broker** - Real-time communication with mobile apps (port 8884)
+2. **Terminal Server** - Secure PTY-based terminal access (port 3001)
+3. **Router** - Path-based reverse proxy for unified access (port 8883)
+4. **Claude Agent** - Manages Claude Code CLI sessions
+5. **File Browser** - Remote file system access
+6. **Git Service** - Git operations and GitHub integration
+7. **Notifications** - Push notifications via Expo
+
+## Security
+
+- Terminal credentials are auto-generated and never logged
+- MQTT authentication is optional but required for ngrok tunnels
+- MQTT/Terminal services bind to localhost only
+- Router is the only public-facing service
+
+## Architecture
+
+```
+src/
+├── index.ts                    # Main entry point
+├── cli/                        # CLI argument parsing
+├── services/                   # Service implementations
+│   ├── mqtt-broker/            # MQTT broker
+│   ├── terminal-server/        # Terminal server
+│   ├── router/                 # HTTP/WS proxy
+│   ├── claude-agent/           # Claude Code CLI management
+│   ├── file-browser/           # File system access
+│   ├── git-service/            # Git operations
+│   ├── notification/           # Push notifications
+│   └── ...                     # Other services
+├── core/                       # Service orchestration
+└── utils/                      # Shared utilities
+```
+
+## Development
+
+```bash
+# Run in development mode
+bun src/index.ts --debug
+
+# Type checking
+bun run type-check
+
+# Build for distribution
+bun run build
+```
+
+## Why Bun?
+
+This project uses Bun because:
+- Native TypeScript support without transpilation
+- Faster startup and runtime performance
+- Built-in WebSocket server (`Bun.serve()`)
+- `bun-pty` for reliable PTY handling (node-pty has compatibility issues)
+- Simpler dependency management
+
+## License
+
+UNLICENSED - Private package