@startanaicompany/cli 1.4.17 → 1.4.19

package/CLAUDE.md

@@ -651,16 +651,405 @@ Uses the same status display logic as the status command (see "Application Statu
 - Domains fallback to `{subdomain}.startanaicompany.com` if not set
 - Branch defaults to 'master' if not specified
 
-### Incomplete Commands
+### Deployments Command Implementation
 
-Several commands still need implementation:
-- `src/commands/env.js` - Not implemented (stub only)
-- `src/commands/domain.js` - Not implemented (stub only)
-- `src/commands/logs.js` - Not implemented (stub only)
-- `src/commands/delete.js` - Not implemented (stub only)
-- `src/commands/whoami.js` - Not implemented (stub only)
+The `deployments` command displays deployment history for the current application in a formatted table.
 
-**Important:** The `env` and `domain` commands need to export OBJECTS with subcommand methods (e.g., `module.exports = { set, get, list }`), not simple functions. See `bin/saac.js:189-219` for how these are called.
+**Usage:**
+```bash
+saac deployments
+saac deploys  # Alias
+
+# With pagination
+saac deployments --limit 10
+saac deployments --limit 20 --offset 20
+```
+
+**How It Works:**
+1. Validates authentication (session token not expired)
+2. Checks for project config (`.saac/config.json`)
+3. Fetches deployment history from `/api/v1/applications/:uuid/deployments`
+4. Displays table with columns: UUID, Status, Branch, Commit, Duration, Trigger, Date
+5. Shows pagination info if more deployments available
+
+**Options:**
+- `-l, --limit <number>` - Number of deployments to show (default: 20)
+- `-o, --offset <number>` - Offset for pagination (default: 0)
+
+**Status Display:**
+- ✅ `finished` - Displayed in green
+- ✗ `failed` - Displayed in red
+- ⏳ `running`, `queued` - Displayed in yellow
+- `unknown` - Displayed in gray
+
+**Table Formatting:**
+- UUID truncated to 26 characters for readability
+- Commit SHA truncated to 7 characters
+- Duration shown in seconds
+- Date formatted with `toLocaleString()`
+
+**Response Fields:**
+```json
+{
+  "deployments": [
+    {
+      "deployment_uuid": "...",
+      "status": "finished",
+      "git_branch": "master",
+      "git_commit": "abc1234",
+      "duration_seconds": 45,
+      "triggered_by": "api",
+      "started_at": "2024-01-20T12:00:00Z"
+    }
+  ],
+  "total": 100
+}
+```
+
+**Next Steps:**
+After viewing deployment history, use:
+- `saac logs --deployment` - View latest deployment logs
+- `saac logs --deployment <uuid>` - View specific deployment logs
+
+### Logs Command Implementation
+
+The `logs` command displays application logs with support for both deployment logs (build logs) and runtime logs (container logs).
+
+**Usage:**
+```bash
+# View latest deployment logs (build logs)
+saac logs --deployment
+saac logs -d
+
+# View specific deployment logs
+saac logs --deployment abc123-def456-...
+saac logs abc123-def456-... --deployment
+
+# View deployment logs in raw format
+saac logs --deployment --raw
+
+# View runtime logs (container logs)
+saac logs
+saac logs --tail 200
+saac logs --follow
+saac logs --since 1h
+```
+
+**Two Modes:**
+
+**1. Deployment Logs Mode (Build Logs)**
+- Enabled with `--deployment` flag
+- Shows logs from the build/deployment process
+- Includes build output, errors, and deployment status
+- Supports both parsed (colorized) and raw formats
+
+**Options:**
+- `--deployment [uuid]` - View deployment logs (omit UUID for latest)
+- `--raw` - Show raw log output (no parsing or colorization)
+- `--include-hidden` - Include hidden log lines
+
+**Display:**
+- Header with deployment UUID, status, commit, duration
+- Parsed logs with stderr highlighted in red
+- Error summary if deployment failed
+- Structured error information with types and details
+
+**2. Runtime Logs Mode (Container Logs)**
+- Default mode when no `--deployment` flag
+- Shows logs from the running container
+- Real-time application output
+
+**Options:**
+- `-t, --tail <lines>` - Number of lines to show (default: 100)
+- `-f, --follow` - Follow log output (not yet implemented)
+- `--since <time>` - Show logs since timestamp
+
+**Error Handling:**
+- 404 error → No deployments found, suggests `saac deploy`
+- 501 error → Runtime logs not implemented, suggests deployment logs
+
+**Response Fields (Deployment Logs):**
+```json
+{
+  "deployment_uuid": "...",
+  "status": "finished",
+  "commit": "abc1234",
+  "commit_message": "Fix bug",
+  "started_at": "2024-01-20T12:00:00Z",
+  "finished_at": "2024-01-20T12:02:00Z",
+  "duration_seconds": 120,
+  "log_count": 150,
+  "logs": [
+    {
+      "type": "stdout",
+      "output": "Installing dependencies..."
+    },
+    {
+      "type": "stderr",
+      "output": "npm WARN deprecated package@1.0.0"
+    }
+  ],
+  "raw_logs": "...",
+  "errors": [
+    {
+      "type": "BUILD_FAILED",
+      "message": "Build failed with exit code 1",
+      "detail": "npm ERR! code ELIFECYCLE"
+    }
+  ]
+}
+```
+
+### Local Development Commands (NEW in 1.5.0)
+
+#### Run Command Implementation
+
+The `run` command allows executing local commands with remote environment variables from the deployed application.
+
+**Usage:**
+```bash
+saac run <command>                  # Run command with remote env vars
+saac run npm start                  # Start app with production env
+saac run --sync npm run build       # Force refresh env vars (skip cache)
+saac run -q npm test                # Quiet mode (suppress warnings)
+```
+
+**Implementation Details:**
+- Fetches env vars from `GET /applications/:uuid/env/export`
+- Uses 5-minute in-memory cache (TTL: 300 seconds)
+- Creates temp file at `/tmp/saac-env-{uuid}.sh` with 0600 permissions
+- Sources env file and executes command in subshell
+- Automatic cleanup on exit (SIGINT/SIGTERM handlers)
+- Rate limit handling (10 requests/minute per user)
+
+**Security Features:**
+- Temp files with 0600 permissions (owner read-write only)
+- Automatic cleanup on process exit
+- Warning message about exposed secrets
+- Cache reduces API calls (rate limit protection)
+
+**Error Handling:**
+- 429 Rate Limit: Shows retry time, mentions caching
+- 403 Forbidden: User doesn't own application
+- 404 Not Found: Application doesn't exist
+- Network failures: Graceful error messages
+
+**Location:** `src/commands/run.js`
+
+---
+
+#### Shell Command Implementation (Project Aurora)
+
+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    # Connect to remote container shell
+```
+
+**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)
+
+**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
+
+Remote Shell: my-app
+
+Connecting to container...
+This may take up to 30 seconds for container creation.
+
+✓ Connected to remote container
+Container is being created, please wait...
+✓ Container is ready!
+Type commands below. Press Ctrl+D or type "exit" to quit.
+
+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
+
+root@container:/app# cd src && pwd
+/app/src
+
+root@container:/app/src# exit
+
+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`
+
+---
+
+### Remote Execution Commands (NEW in 1.6.0)
+
+#### Exec Command Implementation
+
+The `exec` command allows executing commands directly in the deployed application's container.
+
+**Usage:**
+```bash
+saac exec "npm run db:migrate"                    # Run database migrations
+saac exec "npm run build" --timeout 120           # With custom timeout
+saac exec "python manage.py collectstatic" --workdir /app/backend
+saac exec --history                               # View execution history
+saac exec --history --limit 50                    # Show more history
+```
+
+**Implementation Details:**
+- Sends command to `POST /applications/:uuid/exec`
+- Backend validates command against allowlist
+- Python daemon executes via Docker API (no shell interpretation!)
+- Returns: execution_id, exit_code, stdout, stderr, duration
+- Command runs in container as detected user (not root)
+
+**Architecture:**
+```
+CLI → Backend API → Database (exec_requests table) → Python Daemon → Docker Container
+```
+
+**Security Features:**
+- ✅ **3-layer validation:** Backend allowlist + daemon validation + Docker array execution
+- ✅ **Command allowlist:** npm, node, python, bash, etc. (dangerous commands blocked)
+- ✅ **Dangerous pattern detection:** Blocks `rm -rf`, `| sh`, `$(...)`, etc.
+- ✅ **Rate limiting:** 30 requests per 5 minutes per user
+- ✅ **No shell interpretation:** Commands executed as arrays, not strings
+- ✅ **Non-root execution:** Commands run as app user, never privileged
+- ✅ **Audit logging:** All executions logged with user, command, exit code
+
+**Allowed Commands:**
+- Node.js: `npm`, `node`, `npx`, `yarn`, `pnpm`
+- Python: `python`, `python3`, `pip`, `poetry`
+- Ruby: `bundle`, `rake`, `rails`
+- Build tools: `make`, `cmake`, `go`, `cargo`
+- Shell: `sh`, `bash`, `echo`, `cat`, `ls`, `pwd`, `env`
+- Database: `psql`, `mysql`, `mongosh`
+
+**Error Handling:**
+- 400 Validation Error: Command not in allowlist or dangerous pattern detected
+- 408 Timeout: Command exceeded timeout limit (default: 30s, max: 300s)
+- 429 Rate Limit: Too many exec requests (30 per 5 minutes)
+- 503 Container Not Running: Application container is not active
+- 500 Execution Failed: Container error or daemon issue
+
+**Example Output:**
+```bash
+$ saac exec "echo 'Hello from container!'"
+
+Executing Command: myapp
+──────────────────────────
+
+  Command: echo 'Hello from container!'
+  Working Directory: /app
+  Timeout: 30s
+
+✓ Command executed
+
+✓ Execution ID: eb41b197-e215-4f9e-87ac-80ce57e732a6
+
+  Exit Code: 0
+  Duration: 3531ms
+  Started: 1/28/2026, 8:55:37 PM
+  Completed: 1/28/2026, 8:55:41 PM
+
+Standard Output:
+────────────────────────────────────────────────────────────
+Hello from container!
+────────────────────────────────────────────────────────────
+```
+
+**History Command:**
+```bash
+$ saac exec --history
+
+Execution History: myapp
+────────────────────────
+
+╔══════════╤═══════════╤═════════════╤═══════════╤══════════╤═══════════════╗
+║ ID       │ Command   │ Status      │ Exit Code │ Duration │ Started       ║
+╠══════════╪═══════════╪═════════════╪═══════════╪══════════╪═══════════════╣
+║ eb41b197 │ echo '...'│ ✓ completed │ 0         │ 0s       │ 1/28/26, 8:55 ║
+║ a3f2c891 │ npm run...│ ✗ completed │ 1         │ 5s       │ 1/28/26, 8:50 ║
+╚══════════╧═══════════╧═════════════╧═══════════╧══════════╧═══════════════╝
+
+Showing 2 of 5 executions
+```
+
+**Location:** `src/commands/exec.js`
+
+**Backend Implementation:**
+- Database table: `exec_requests` (status: pending → running → completed/failed/timeout)
+- Python daemon: `/root/exec-daemon/exec_daemon.py` (polls every 2 seconds)
+- Systemd service: `exec-daemon.service` (auto-restart, logs to `/var/log/exec-daemon.log`)
+
+---
+
+**Backend Requirements (Implemented):**
+- `GET /api/v1/applications/:uuid/env/export` - Export endpoint (deployed 2026-01-28)
+- Returns: `environment` (object), `export_script` (bash format), `dotenv_format` (dotenv format)
+- Rate limit: 10 requests/minute per user
+- Authentication: X-Session-Token or X-API-Key
+- Response includes `expires_in: 300` (5-minute cache recommendation)
+- `POST /api/v1/applications/:uuid/exec` - Execute command in container (deployed 2026-01-28)
+- `GET /api/v1/applications/:uuid/exec/history` - View execution history (deployed 2026-01-28)
+- Rate limit: 30 requests per 5 minutes per user
 
 **Implementation Pattern for New Commands:**
 1. Require flags, no interactive prompts (exception: `init` uses inquirer for app selection)
@@ -669,15 +1058,6 @@ Several commands still need implementation:
 4. Use spinners for async operations
 5. Handle errors with descriptive messages
 
-**Example Module Structure for env.js:**
-```javascript
-async function set(vars) { /* implementation */ }
-async function get(key) { /* implementation */ }
-async function list() { /* implementation */ }
-
-module.exports = { set, get, list };
-```
-
 ### MailHog Integration
 
 The system uses MailHog for email verification in development:
@@ -697,7 +1077,7 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - During registration, Gitea username can be auto-detected or manually provided
 - Applications reference repositories in the format: `git@git.startanaicompany.com:user/repo.git`
 
-## Current Status - Version 1.4.17
+## Current Status - Version 1.6.0
 
 ### Completed Features
 
@@ -728,17 +1108,33 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - ✅ `saac update` - Update application configuration (PATCH endpoint)
 - ✅ `saac init` - Link existing application to current directory (interactive)
 - ✅ `saac deploy` - Trigger deployment for current application
+- ✅ `saac deployments` - List deployment history with table display
+- ✅ `saac logs` - View deployment logs (build logs) or runtime logs (container logs)
 - ✅ `saac list` - List all applications with table display
 - ✅ `saac status` - Show login status, user info, and applications
+- ✅ `saac delete` - Delete application with confirmation prompt
+- ✅ `saac whoami` - Show current user information
+
+**Environment & Domain Management:**
+- ✅ `saac env set/get/list` - Manage environment variables (fully implemented)
+- ✅ `saac domain set/show` - Manage application domain (fully implemented)
+
+**Local Development (Phase 1):**
+- ✅ `saac run <command>` - Execute local command 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
+- Features: Command allowlist, dangerous pattern detection, rate limiting (30/5min), audit logging
 
-**Incomplete Commands:**
-- ⏳ `saac logs` - Not implemented (stub only)
-- ⏳ `saac env` - Not implemented (stub only, needs to export object with set/get/list methods)
-- ⏳ `saac domain` - Not implemented (stub only, needs to export object with set/show methods)
-- ⏳ `saac delete` - Not implemented (stub only)
-- ⏳ `saac whoami` - Not implemented (stub only)
-- ✅ `saac deploy` - Fully implemented
-- ✅ `saac list` - Fully implemented
+**All Commands Implemented!** ✅ No incomplete commands remain
 
 ### Critical Learnings & Bug Fixes
 
@@ -780,7 +1176,7 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 
 ### API Endpoint Reference
 
-**Correct Endpoint Paths (v1.4.12):**
+**Correct Endpoint Paths (v1.5.0):**
 - `POST /api/v1/users/register` - Register (email only, git_username optional)
 - `POST /api/v1/users/verify` - Verify email with code
 - `POST /api/v1/auth/login` - Login with API key, get session token
@@ -796,7 +1192,10 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - `GET /api/v1/applications` - List applications
 - `PATCH /api/v1/applications/:uuid` - Update application
 - `POST /api/v1/applications/:uuid/deploy` - Deploy application
-- `GET /api/v1/applications/:uuid/logs` - Get logs
+- `GET /api/v1/applications/:uuid/deployments` - Get deployment history (NEW in 1.4.17)
+- `GET /api/v1/applications/:uuid/deployment-logs` - Get deployment logs (NEW in 1.4.17)
+- `GET /api/v1/applications/:uuid/logs` - Get runtime logs (container logs)
+- `GET /api/v1/applications/:uuid/env/export` - Export environment variables (NEW in 1.5.0)
 - `DELETE /api/v1/applications/:uuid` - Delete application
 
 **Important:** OAuth endpoints (`/oauth/*`) do NOT have the `/api/v1` prefix!
@@ -917,4 +1316,4 @@ Before publishing to npm:
 - `dotenv` - Environment variables
 - `open` - Open browser for OAuth (v8.4.2 for compatibility with chalk v4)
 
-**Version:** 1.4.17 (current)
+**Version:** 1.5.0 (current)

package/bin/saac.js

@@ -22,6 +22,7 @@ const init = require('../src/commands/init');
 const create = require('../src/commands/create');
 const update = require('../src/commands/update');
 const deploy = require('../src/commands/deploy');
+const deployments = require('../src/commands/deployments');
 const logs = require('../src/commands/logs');
 const env = require('../src/commands/env');
 const domain = require('../src/commands/domain');
@@ -30,6 +31,9 @@ const list = require('../src/commands/list');
 const status = require('../src/commands/status');
 const whoami = require('../src/commands/whoami');
 const manual = require('../src/commands/manual');
+const run = require('../src/commands/run');
+const shell = require('../src/commands/shell');
+const execCmd = require('../src/commands/exec');
 
 // Configure CLI
 program
@@ -200,12 +204,60 @@ program
   .action(deploy);
 
 program
-  .command('logs')
-  .description('View application logs')
-  .option('-t, --tail <lines>', 'Number of lines to show', '100')
-  .option('-f, --follow', 'Follow log output')
+  .command('deployments')
+  .alias('deploys')
+  .description('List deployment history')
+  .option('-l, --limit <number>', 'Number of deployments to show', '20')
+  .option('-o, --offset <number>', 'Offset for pagination', '0')
+  .action(deployments);
+
+program
+  .command('logs [deploymentUuid]')
+  .description('View application logs (runtime or deployment logs)')
+  .option('-d, --deployment [uuid]', 'View deployment logs (build logs)')
+  .option('--raw', 'Show raw log output (deployment logs only)')
+  .option('--include-hidden', 'Include hidden log lines (deployment logs only)')
+  .option('-t, --tail <lines>', 'Number of lines to show (runtime logs only)', '100')
+  .option('-f, --follow', 'Follow log output (runtime logs only)')
+  .option('--since <time>', 'Show logs since timestamp (runtime logs only)')
   .action(logs);
 
+// Local development commands
+program
+  .command('run <command>')
+  .description('Run local command with remote environment variables')
+  .option('--sync', 'Force refresh environment variables (skip cache)')
+  .option('-q, --quiet', 'Quiet mode (suppress warnings)')
+  .action(run);
+
+program
+  .command('shell')
+  .description('Open interactive remote shell (inside container via WebSocket)')
+  .action(shell);
+
+// Remote execution commands
+program
+  .command('exec [command]')
+  .description('Execute command in remote container')
+  .option('--workdir <path>', 'Working directory (default: /app)')
+  .option('--timeout <seconds>', 'Timeout in seconds (default: 30, max: 300)', '30')
+  .option('--history', 'View execution history')
+  .option('--limit <number>', 'Limit for history (default: 20, max: 100)', '20')
+  .option('--offset <number>', 'Offset for history pagination (default: 0)', '0')
+  .action((command, options) => {
+    if (options.history) {
+      execCmd.history(options);
+    } else if (command) {
+      execCmd.exec(command, options);
+    } else {
+      console.error('Error: command is required (unless using --history)');
+      console.log('\nUsage:');
+      console.log('  saac exec <command>           Execute command');
+      console.log('  saac exec --history           View execution history');
+      process.exit(1);
+    }
+  });
+
 // Environment variable commands
 const envCommand = program
   .command('env')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startanaicompany/cli",
-  "version": "1.4.17",
+  "version": "1.4.19",
   "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"