@naarang/ccc 1.0.14 → 1.1.0-beta.1

package/README.md

@@ -20,9 +20,20 @@ CCC is a powerful CLI tool that creates a bridge between [Claude Code](https://c
   <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
@@ -30,6 +41,7 @@ CCC is a powerful CLI tool that creates a bridge between [Claude Code](https://c
 - **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 in mobile app with authentication
 - **Remote Access** - Optional ngrok integration for access from anywhere
 - **Secure MQTT** - Built-in MQTT broker with authentication support
 - **Session Management** - Persistent sessions across reconnections
@@ -96,15 +108,20 @@ Open the app, create a project pointing to your local directory, and start chatt
 ccc [options]
 
 Options:
-  --debug                      Enable debug logging
-  -u, --username <user>        MQTT broker username
-  -p, --password <pass>        MQTT broker password
-  --port <port>                MQTT broker port (default: 8883)
-  -t, --ngrok-token <token>    ngrok auth token (enables public tunnel)
-  --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
+  --debug                           Enable debug logging
+  -u, --username <user>             MQTT broker username
+  -p, --password <pass>             MQTT broker password
+  --mqtt-port <port>                Internal MQTT broker port (default: 8883)
+  --port <port>                     [DEPRECATED] Use --mqtt-port instead
+  --router-port <port>              Router port for ngrok (default: 8080)
+  --terminal-port <port>            Internal terminal server port (default: 3001)
+  --terminal-username <user>        Terminal authentication username (enables terminal)
+  --terminal-password <pass>        Terminal authentication password (enables terminal)
+  -t, --ngrok-token <token>         ngrok auth token (enables public tunnel)
+  --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
 ```
 
 > **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.
@@ -121,19 +138,26 @@ ccc
 ccc -u admin -p secret
 ```
 
+**With terminal access (Beta):**
+```bash
+ccc --terminal-username admin --terminal-password secret
+```
+
 **With ngrok for remote access:**
 ```bash
 ccc --ngrok-token YOUR_NGROK_TOKEN
 ```
 
-**Custom port with debug logging:**
+**Full example with ngrok, authentication, and terminal:**
 ```bash
-ccc --port 9000 --debug
+ccc --ngrok-token YOUR_TOKEN \
+    --terminal-username admin \
+    --terminal-password secret
 ```
 
-**Full example with ngrok and authentication:**
+**Custom ports with debug logging:**
 ```bash
-ccc -u admin -p secret -t YOUR_TOKEN --ngrok-domain myapp.ngrok.app
+ccc --mqtt-port 9000 --terminal-port 3002 --debug
 ```
 
 ### Environment Variables
@@ -141,15 +165,126 @@ ccc -u admin -p secret -t YOUR_TOKEN --ngrok-domain myapp.ngrok.app
 Create a `.env` file in your working directory:
 
 ```env
+# MQTT Configuration
 MQTT_BROKER_PORT=8883
 MQTT_USERNAME=your-username
 MQTT_PASSWORD=your-password
+
+# Router Configuration
+ROUTER_PORT=8080
+
+# Terminal Configuration (Beta)
+TERMINAL_PORT=3001
+TERMINAL_USERNAME=your-terminal-username
+TERMINAL_PASSWORD=your-terminal-password
+
+# Ngrok Configuration
 NGROK_AUTH_TOKEN=your-ngrok-token
 NGROK_DOMAIN=your-custom-domain.ngrok.app
 ```
 
 > **Note:** CLI arguments override environment variables
 
+## 🖥️ 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.
+
+### Enabling Terminal Access
+
+Terminal access is **opt-in** for security reasons. To enable it, you must provide authentication credentials:
+
+```bash
+ccc --terminal-username admin --terminal-password your-secure-password
+```
+
+Or via environment variables:
+```env
+TERMINAL_USERNAME=admin
+TERMINAL_PASSWORD=your-secure-password
+```
+
+### 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)
+   - Project path updates automatically when switching projects
+   - 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
+- ✅ Automatic resize on orientation change
+- ✅ Custom theme matching app design
+- ✅ Scrollback history
+
+### Usage from Mobile App
+
+Once enabled on the backend:
+1. Open CCC mobile app
+2. Navigate to project settings
+3. Terminal tab will appear 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. **Use Strong Passwords:** Terminal gives full shell access
+   ```bash
+   # Generate a secure password
+   openssl rand -base64 32
+   ```
+
+2. **Combine with ngrok Authentication:** For remote access
+   ```bash
+   ccc --ngrok-token YOUR_TOKEN \
+       --terminal-username admin \
+       --terminal-password $(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
+
+### Troubleshooting Terminal
+
+**Terminal won't connect:**
+- Verify credentials are correct
+- Check logs with `--debug` flag
+- Ensure port 3001 is not in use
+
+**Authentication failures:**
+- Check for IP blocking (max 5 failed attempts)
+- Wait 15 minutes if blocked
+- Restart server to clear blocks
+
+**Terminal not showing in app:**
+- Ensure terminal credentials are set on backend
+- Restart the mobile app
+- Check app settings for terminal configuration
+
 ## Permission Modes
 
 CCC offers four permission modes to balance convenience and security:
@@ -179,11 +314,14 @@ CCC offers four permission modes to balance convenience and security:
 
 When you start CCC, it:
 
-1. **Starts MQTT Broker** - Embedded broker on port 8883 (WebSocket)
-2. **Sets Up Projects** - Auto-configures permission hooks
-3. **Manages Sessions** - Persistent sessions across disconnects
-4. **Streams Responses** - Real-time Claude responses to mobile
-5. **Handles Permissions** - Smart permission checks based on mode
+1. **Starts MQTT Broker** - Embedded broker on port 8883 (localhost)
+2. **Starts Path Router** - HTTP router on port 8080 proxying MQTT and terminal
+3. **Starts Terminal Server** (Optional) - Web terminal on port 3001 if credentials provided
+4. **Sets Up ngrok Tunnel** (Optional) - Public URL pointing to router
+5. **Sets Up Projects** - Auto-configures permission hooks
+6. **Manages Sessions** - Persistent sessions across disconnects
+7. **Streams Responses** - Real-time Claude responses to mobile
+8. **Handles Permissions** - Smart permission checks based on mode
 
 ### Project Structure
 
@@ -210,15 +348,27 @@ The CCC mobile app is required to interact with the backend.
   <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) - when enabled on backend
 - Server profile management
 - Connection health monitoring
 - Theme support (light/dark)