@startanaicompany/cli 1.4.18 → 1.4.20

package/CLAUDE.md

@@ -838,58 +838,102 @@ saac run -q npm test                # Quiet mode (suppress warnings)
 
 ---
 
-#### Shell Command Implementation
+#### Shell Command Implementation (Project Aurora)
 
-The `shell` command opens an interactive shell with remote environment variables loaded.
+The `shell` command provides a **TRUE remote shell** - you're actually inside the Docker container, not just a local shell with env vars loaded. This is powered by Project Aurora (WebSocket + Docker + tmux).
+
+**Key Difference from Phase 1:**
+- **OLD (Phase 1)**: Local shell with remote env vars → wrong filesystem, wrong tools, wrong paths
+- **NEW (Aurora)**: Remote shell inside container → TRUE remote experience like SSH/Railway
 
 **Usage:**
 ```bash
-saac shell                         # Open shell (uses $SHELL or /bin/bash)
-saac shell --cmd zsh               # Use specific shell
-saac shell --sync                  # Force refresh env vars (skip cache)
+saac shell    # Connect to remote container shell
 ```
 
-**Implementation Details:**
-- Fetches env vars from `GET /applications/:uuid/env/export`
-- Uses 5-minute in-memory cache (same as `run`)
-- Creates temp file for env vars at `/tmp/saac-env-{uuid}.sh`
-- Special handling for bash and zsh (custom RC files)
-- Sources environment before shell starts
-- Automatic cleanup when shell exits
-
-**Shell-Specific Behavior:**
-- **bash:** Uses `--rcfile` with temporary RC that sources env + user's `.bashrc`
-- **zsh:** Uses `ZDOTDIR` with temporary `.zshrc` that sources env + user's `.zshrc`
-- **other:** Fallback to bash with source then exec
+**Architecture:**
+- WebSocket client connects to backend server
+- Backend creates Docker container with tmux session
+- Commands sent via WebSocket, executed in container
+- Terminal output captured from tmux and streamed back
+- Session persists even after disconnect (up to 1 hour idle)
 
-**Security Features:**
-- Same as `run` command (0600 permissions, cleanup, warnings)
-- Sets environment variables: `SAAC_ENV_LOADED=1`, `SAAC_APP_NAME`, `SAAC_APP_UUID`
+**Implementation Details:**
+- Uses `ws` package for WebSocket client
+- Connects to: `wss://apps.startanaicompany.com/api/v1/shell/connect`
+- Authentication via session token or API key
+- Readline interface for local terminal interaction
+- Automatic reconnection on disconnect (up to 3 attempts)
+- Heartbeat ping/pong every 30 seconds
+
+**Session Lifecycle:**
+1. CLI connects via WebSocket with auth token
+2. Backend creates session record in database (status: 'creating')
+3. Python daemon creates Docker container with tmux
+4. Container ready, status updates to 'active'
+5. User interacts with remote shell
+6. On disconnect, session marked 'idle' (persists for 1 hour)
+7. Idle timeout or manual termination cleans up container
+
+**Features:**
+- ✅ TRUE remote shell (inside container, not local)
+- ✅ Persistent session (survives reconnections)
+- ✅ Interactive commands (vim, nano, etc work!)
+- ✅ Working directory persists between commands
+- ✅ Command history (up arrow works)
+- ✅ Real-time output streaming
+- ✅ Ctrl+C sends to remote shell
+
+**Connection Handling:**
+- 30-second timeout for initial container creation
+- Auto-reconnect on network issues (3 attempts, exponential backoff)
+- Graceful cleanup on exit (Ctrl+D or "exit" command)
 
 **User Experience:**
 ```bash
 $ saac shell
-✓ Environment variables retrieved
 
-🚀 Opening shell with 6 environment variables loaded
+Remote Shell: my-app
+
+Connecting to container...
+This may take up to 30 seconds for container creation.
 
-  Application:  my-app
-  Shell:        bash
-  Variables:    6
+✓ Connected to remote container
+Container is being created, please wait...
+✓ Container is ready!
+Type commands below. Press Ctrl+D or type "exit" to quit.
 
-⚠️  Secrets are exposed on local machine
-Temporary file: /tmp/saac-env-abc123.sh (will be deleted on exit)
+root@container:/app# ls -la
+total 48
+drwxr-xr-x  6 root root 4096 Jan 28 20:00 .
+drwxr-xr-x 18 root root 4096 Jan 28 20:00 ..
+-rw-r--r--  1 root root  220 Jan 28 20:00 package.json
+drwxr-xr-x  2 root root 4096 Jan 28 20:00 src
 
-Type "exit" or press Ctrl+D to close the shell
-────────────────────────────────────────────────────────────────
+root@container:/app# cd src && pwd
+/app/src
 
-bash-5.0$ echo $NODE_ENV
-production
-bash-5.0$ exit
+root@container:/app/src# exit
 
-✓ Shell closed, environment variables cleared
+Disconnecting from remote shell...
 ```
 
+**Error Handling:**
+- `Authentication failed` → Token expired, run `saac login`
+- `Access denied` → User doesn't own the application
+- `Connection timeout` → Server unavailable or container failed to start
+- `Max reconnection attempts` → Network issue, try again later
+
+**Backend Requirements:**
+- WebSocket server at `/api/v1/shell/connect` endpoint
+- PostgreSQL tables: `shell_sessions`, `shell_commands`, `shell_output`
+- Python daemon managing Docker containers with tmux
+- Session cleanup after 1 hour idle or 4 hours total
+
+**Location:** `src/commands/shell.js` (403 lines, complete rewrite for Aurora)
+
+**Note:** Backend infrastructure (WebSocket server + Python daemon) must be deployed before this command works. CLI is ready, waiting for backend Phase 3.5 deployment.
+
 **Location:** `src/commands/shell.js`
 
 ---
@@ -1075,11 +1119,16 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - ✅ `saac env set/get/list` - Manage environment variables (fully implemented)
 - ✅ `saac domain set/show` - Manage application domain (fully implemented)
 
-**Local Development (NEW in 1.5.0):**
+**Local Development (Phase 1):**
 - ✅ `saac run <command>` - Execute local command with remote environment variables
-- ✅ `saac shell` - Open interactive shell with remote environment variables
 - Features: 5-minute caching, secure temp files (0600), automatic cleanup, rate limit handling
 
+**Remote Shell (Project Aurora - Phase 3.5):**
+- ✅ `saac shell` - TRUE remote shell inside Docker container via WebSocket
+- Features: Persistent sessions (tmux), interactive (vim/nano work), real-time output, auto-reconnect
+- Architecture: WebSocket client + PostgreSQL + Python daemon + Docker + tmux
+- **Status:** CLI ready, waiting for backend deployment
+
 **Remote Execution (NEW in 1.6.0):**
 - ✅ `saac exec <command>` - Execute commands in remote container
 - ✅ `saac exec --history` - View execution history

package/bin/saac.js

@@ -232,9 +232,7 @@ program
 
 program
   .command('shell')
-  .description('Open interactive shell with remote environment variables')
-  .option('--cmd <shell>', 'Shell to use (default: $SHELL or /bin/bash)')
-  .option('--sync', 'Force refresh environment variables (skip cache)')
+  .description('Open interactive remote shell (inside container via WebSocket)')
   .action(shell);
 
 // Remote execution commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startanaicompany/cli",
-  "version": "1.4.18",
+  "version": "1.4.20",
   "description": "Official CLI for StartAnAiCompany.com - Deploy AI recruitment sites with ease",
   "main": "src/index.js",
   "bin": {
@@ -44,7 +44,8 @@
     "open": "^8.4.2",
     "ora": "^5.4.1",
     "table": "^6.8.1",
-    "validator": "^13.11.0"
+    "validator": "^13.11.0",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "eslint": "^8.54.0"

package/src/commands/env.js

@@ -105,7 +105,7 @@ async function list() {
  * Set environment variables
  * @param {string[]} vars - Array of KEY=VALUE pairs
  */
-async function set(...vars) {
+async function set(vars) {
   try {
     // Check authentication
     if (!isAuthenticated()) {

package/src/commands/logs.js

@@ -188,11 +188,20 @@ async function getRuntimeLogs(applicationUuid, applicationName, options) {
     logger.newline();
 
     // Display logs
-    if (result.logs && result.logs.length > 0) {
-      result.logs.forEach(log => {
-        console.log(log);
-      });
+    if (result.logs) {
+      if (Array.isArray(result.logs)) {
+        // Logs is an array
+        result.logs.forEach(log => {
+          console.log(log);
+        });
+      } else if (typeof result.logs === 'string') {
+        // Logs is a string (most common format from backend)
+        console.log(result.logs);
+      } else {
+        logger.warn('Unexpected log format');
+      }
     } else if (typeof result === 'string') {
+      // Entire result is a string
       console.log(result);
     } else {
       logger.warn('No logs available');

package/src/commands/shell.js

@@ -1,55 +1,321 @@
 /**
- * Shell Command - Open interactive shell with remote environment variables
+ * Shell Command - Interactive remote shell via WebSocket (Project Aurora)
+ *
+ * This command provides a TRUE remote shell experience - you're actually inside
+ * the container, not just a local shell with env vars loaded.
  */
 
-const api = require('../lib/api');
-const { getProjectConfig, isAuthenticated } = require('../lib/config');
+const WebSocket = require('ws');
+const readline = require('readline');
+const { getProjectConfig, isAuthenticated, getUser, getApiUrl } = require('../lib/config');
 const logger = require('../lib/logger');
-const { spawn } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-// In-memory cache for environment variables (5 minutes TTL)
-const envCache = new Map();
-const CACHE_TTL = 300000; // 5 minutes in milliseconds
 
 /**
- * Get environment variables (with caching)
- * @param {string} appUuid - Application UUID
- * @param {boolean} forceRefresh - Skip cache and fetch fresh
+ * WebSocket Shell Client
+ * Connects to backend WebSocket server and provides interactive shell
  */
-async function getEnvironmentVariables(appUuid, forceRefresh = false) {
-  // Check cache first
-  if (!forceRefresh) {
-    const cached = envCache.get(appUuid);
-    if (cached) {
-      const age = Date.now() - cached.timestamp;
-      if (age < CACHE_TTL) {
-        logger.info('📦 Using cached environment variables (updated <5 min ago)');
-        return cached.data;
+class ShellClient {
+  constructor(serverUrl, token, applicationUuid) {
+    this.serverUrl = serverUrl;
+    this.token = token;
+    this.applicationUuid = applicationUuid;
+    this.ws = null;
+    this.sessionId = null;
+    this.connected = false;
+    this.rl = null;
+    this.lastScreen = '';
+    this.reconnectAttempts = 0;
+    this.maxReconnectAttempts = 3;
+    this.shouldReconnect = true;
+  }
+
+  async connect() {
+    return new Promise((resolve, reject) => {
+      // Build WebSocket URL
+      const wsUrl = this.buildWebSocketUrl();
+
+      logger.info('Connecting to remote shell...');
+
+      this.ws = new WebSocket(wsUrl, {
+        headers: {
+          'X-Session-Token': this.token,
+        },
+        // Handle HTTPS/WSS
+        rejectUnauthorized: process.env.NODE_ENV === 'production'
+      });
+
+      // Connection timeout
+      const timeout = setTimeout(() => {
+        reject(new Error('Connection timeout'));
+        if (this.ws) {
+          this.ws.close();
+        }
+      }, 30000); // 30 second timeout for container creation
+
+      this.ws.on('open', () => {
+        clearTimeout(timeout);
+        this.connected = true;
+        this.reconnectAttempts = 0;
+        logger.success('Connected to remote container');
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const message = JSON.parse(data.toString());
+          this.handleMessage(message);
+        } catch (err) {
+          logger.error('Error parsing message:', err.message);
+        }
+      });
+
+      this.ws.on('close', (code, reason) => {
+        this.connected = false;
+        const reasonText = reason ? reason.toString() : '';
+
+        if (code === 1000) {
+          // Normal closure
+          logger.info('Disconnected from remote shell');
+        } else {
+          logger.warn(`Disconnected: ${code}${reasonText ? ' - ' + reasonText : ''}`);
+
+          if (this.shouldReconnect && code !== 4001 && code !== 4003) {
+            this.handleReconnect();
+          }
+        }
+      });
+
+      this.ws.on('error', (error) => {
+        clearTimeout(timeout);
+
+        // Check for specific error codes
+        if (error.message.includes('401') || error.message.includes('Unauthorized')) {
+          logger.error('Authentication failed');
+          reject(new Error('Authentication failed'));
+        } else if (error.message.includes('403') || error.message.includes('Forbidden')) {
+          logger.error('Access denied - you do not own this application');
+          reject(new Error('Access denied'));
+        } else {
+          logger.error('WebSocket error:', error.message);
+          reject(error);
+        }
+      });
+    });
+  }
+
+  buildWebSocketUrl() {
+    // Convert HTTP(S) URL to WS(S) URL
+    const apiUrl = this.serverUrl;
+    let wsUrl = apiUrl.replace(/^http:\/\//, 'ws://').replace(/^https:\/\//, 'wss://');
+
+    // Remove /api/v1 suffix if present
+    wsUrl = wsUrl.replace(/\/api\/v1$/, '');
+
+    // Build shell connect endpoint
+    wsUrl = `${wsUrl}/api/v1/shell/connect?app=${this.applicationUuid}&token=${this.token}`;
+
+    return wsUrl;
+  }
+
+  handleMessage(message) {
+    switch (message.type) {
+      case 'control':
+        this.handleControlMessage(message);
+        break;
+
+      case 'output':
+        this.handleOutputMessage(message);
+        break;
+
+      case 'pong':
+        // Heartbeat response
+        break;
+
+      default:
+        logger.warn('Unknown message type:', message.type);
+    }
+  }
+
+  handleControlMessage(message) {
+    if (message.action === 'session_ready') {
+      this.sessionId = message.data.session_id;
+      const status = message.data.status;
+
+      if (status === 'creating') {
+        logger.info('Container is being created, please wait...');
+      } else if (status === 'active') {
+        logger.success('Shell session ready!');
+        logger.info('Type commands below. Press Ctrl+D or type "exit" to quit.');
+        logger.newline();
+
+        // Start terminal interface
+        this.startTerminal();
+      }
+    } else if (message.action === 'session_active') {
+      logger.success('Container is ready!');
+      logger.info('Type commands below. Press Ctrl+D or type "exit" to quit.');
+      logger.newline();
+
+      // Start terminal interface
+      if (!this.rl) {
+        this.startTerminal();
+      }
+    } else if (message.action === 'error') {
+      logger.error('Server error:', message.data.message);
+    }
+  }
+
+  handleOutputMessage(message) {
+    const screen = message.data.screen;
+
+    // Only update if screen changed
+    if (screen !== this.lastScreen) {
+      // Clear current readline prompt
+      if (this.rl) {
+        readline.clearLine(process.stdout, 0);
+        readline.cursorTo(process.stdout, 0);
+      }
+
+      // Display full screen content
+      // For better UX, only show last 40 lines
+      const lines = screen.split('\n');
+      const displayLines = lines.slice(-40);
+
+      console.log(displayLines.join('\n'));
+
+      this.lastScreen = screen;
+    }
+
+    // Show prompt again
+    if (this.rl) {
+      this.rl.prompt(true);
+    }
+  }
+
+  startTerminal() {
+    // Create readline interface
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: '',  // No prompt - we get it from the container
+      terminal: true,
+      historySize: 1000
+    });
+
+    // Handle user input
+    this.rl.on('line', (input) => {
+      const command = input.trim();
+
+      // Local exit command
+      if (command === 'exit' || command === 'quit') {
+        this.cleanup();
+        return;
+      }
+
+      // Send command to server
+      if (this.connected && this.ws.readyState === WebSocket.OPEN) {
+        this.sendCommand(command);
+      } else {
+        logger.error('Not connected to server');
+      }
+    });
+
+    // Handle Ctrl+C (SIGINT)
+    this.rl.on('SIGINT', () => {
+      // Send Ctrl+C to remote shell
+      if (this.connected) {
+        this.sendCommand('\x03'); // ASCII ETX (Ctrl+C)
       }
-      // Cache expired
-      envCache.delete(appUuid);
+      this.rl.prompt();
+    });
+
+    // Handle Ctrl+D (EOF) - exit
+    process.stdin.on('keypress', (str, key) => {
+      if (key && key.ctrl && key.name === 'd') {
+        this.cleanup();
+      }
+    });
+
+    // Enable keypress events
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(false); // Keep cooked mode for line editing
+    }
+  }
+
+  sendCommand(command) {
+    if (!this.connected || this.ws.readyState !== WebSocket.OPEN) {
+      logger.error('Not connected to server');
+      return false;
+    }
+
+    const message = {
+      type: 'command',
+      data: {
+        command: command
+      }
+    };
+
+    this.ws.send(JSON.stringify(message));
+    return true;
+  }
+
+  async handleReconnect() {
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      logger.error('Max reconnection attempts reached. Exiting.');
+      this.cleanup();
+      return;
+    }
+
+    this.reconnectAttempts++;
+    const delay = 2000 * this.reconnectAttempts; // Exponential backoff
+
+    logger.info(`Reconnecting in ${delay/1000}s... (${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+
+    await new Promise(resolve => setTimeout(resolve, delay));
+
+    try {
+      await this.connect();
+    } catch (err) {
+      logger.error('Reconnection failed:', err.message);
     }
   }
 
-  // Fetch from API
-  const client = api.createClient();
-  const response = await client.get(`/applications/${appUuid}/env/export`);
+  cleanup() {
+    logger.newline();
+    logger.info('Disconnecting from remote shell...');
+
+    this.shouldReconnect = false;
+
+    if (this.rl) {
+      this.rl.close();
+      this.rl = null;
+    }
 
-  // Cache for 5 minutes
-  envCache.set(appUuid, {
-    data: response.data,
-    timestamp: Date.now()
-  });
+    if (this.ws) {
+      this.ws.close(1000, 'Client closing');
+      this.ws = null;
+    }
+
+    // Restore terminal
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(false);
+    }
 
-  return response.data;
+    process.exit(0);
+  }
+
+  startHeartbeat() {
+    // Send ping every 30 seconds to keep connection alive
+    setInterval(() => {
+      if (this.connected && this.ws.readyState === WebSocket.OPEN) {
+        this.ws.send(JSON.stringify({ type: 'ping', timestamp: Date.now() }));
+      }
+    }, 30000);
+  }
 }
 
 /**
- * Open interactive shell with remote environment variables
- * @param {object} options - Command options
+ * Shell command main function
  */
 async function shell(options = {}) {
   try {
@@ -72,93 +338,64 @@ async function shell(options = {}) {
 
     const { applicationUuid, applicationName } = projectConfig;
 
-    // Fetch environment variables
-    logger.newline();
-    const spin = logger.spinner('Fetching environment variables...').start();
-
-    let envData;
-    try {
-      envData = await getEnvironmentVariables(applicationUuid, options.sync);
-      spin.succeed('Environment variables retrieved');
-    } catch (error) {
-      spin.fail('Failed to fetch environment variables');
-
-      if (error.response?.status === 429) {
-        const retryAfter = error.response.headers['retry-after'] || 60;
-        logger.newline();
-        logger.error(`Rate limit exceeded. Too many requests.`);
-        logger.info(`Retry in ${retryAfter} seconds.`);
-        logger.newline();
-        logger.info('Note: Environment variables are cached for 5 minutes.');
-        process.exit(1);
-      }
+    // Get user and token
+    const user = getUser();
+    const token = user.sessionToken || user.apiKey;
 
-      throw error;
+    if (!token) {
+      logger.error('No authentication token found. Please login again.');
+      process.exit(1);
     }
 
-    logger.newline();
-
-    // Determine shell to use
-    const userShell = options.cmd || process.env.SHELL || '/bin/bash';
-    const shellName = path.basename(userShell);
+    // Get server URL
+    const serverUrl = getApiUrl();
 
-    // Display info
-    logger.success(`🚀 Opening shell with ${envData.variable_count} environment variables loaded`);
+    // Show banner
     logger.newline();
-    logger.field('  Application', applicationName);
-    logger.field('  Shell', shellName);
-    logger.field('  Variables', envData.variable_count);
+    logger.section(`Remote Shell: ${applicationName}`);
     logger.newline();
-    logger.warn('⚠️  Secrets are exposed on local machine');
-    logger.newline();
-    logger.info('Type "exit" or press Ctrl+D to close the shell');
-    logger.section('─'.repeat(60));
+    logger.info('Connecting to container...');
+    logger.info('This may take up to 30 seconds for container creation.');
     logger.newline();
 
-    // Merge remote environment variables with current process env
-    const mergedEnv = {
-      ...process.env,
-      ...envData.environment,
-      SAAC_ENV_LOADED: '1',
-      SAAC_APP_NAME: applicationName,
-      SAAC_APP_UUID: applicationUuid
-    };
+    // Create shell client
+    const client = new ShellClient(serverUrl, token, applicationUuid);
 
-    // Determine shell arguments for interactive mode
-    let shellArgs = [];
-    if (shellName === 'bash' || shellName === 'sh') {
-      shellArgs = ['-i']; // Interactive mode
-    } else if (shellName === 'zsh') {
-      shellArgs = ['-i']; // Interactive mode
-    } else if (shellName === 'fish') {
-      shellArgs = ['-i']; // Interactive mode
-    }
-    // If custom shell, try -i flag (most shells support it)
-    else if (!userShell.includes('/')) {
-      shellArgs = ['-i'];
-    }
-
-    // Spawn shell directly with merged environment
-    const shellProc = spawn(userShell, shellArgs, {
-      stdio: 'inherit',
-      cwd: process.cwd(),
-      env: mergedEnv
+    // Handle process termination
+    process.on('SIGTERM', () => {
+      client.cleanup();
     });
 
-    shellProc.on('exit', (code) => {
-      logger.newline();
-      logger.success('✓ Shell closed, environment variables cleared');
-      process.exit(code || 0);
+    process.on('SIGINT', () => {
+      // Let readline handle SIGINT
     });
 
-    shellProc.on('error', (error) => {
-      logger.newline();
-      logger.error(`Failed to open shell: ${error.message}`);
+    // Connect to server
+    try {
+      await client.connect();
+
+      // Start heartbeat
+      client.startHeartbeat();
+
+    } catch (err) {
+      if (err.message === 'Authentication failed') {
+        logger.error('Authentication failed. Please login again:');
+        logger.log('  saac login');
+      } else if (err.message === 'Access denied') {
+        logger.error('Access denied. You do not own this application.');
+      } else if (err.message === 'Connection timeout') {
+        logger.error('Connection timeout. The server may be unavailable or the container failed to start.');
+        logger.info('Please try again later or check application status:');
+        logger.log('  saac status');
+      } else {
+        logger.error('Failed to connect:', err.message);
+        logger.info('Please check your network connection and try again.');
+      }
       process.exit(1);
-    });
+    }
 
   } catch (error) {
-    logger.error(error.response?.data?.message || error.message);
+    logger.error(error.message);
     process.exit(1);
   }
 }