@startanaicompany/cli 1.9.1 → 1.9.3

package/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code when working with the SAAC CLI codeba
 
 SAAC CLI is the official command-line interface for StartAnAiCompany.com. Built with Node.js and Commander.js, it interfaces with a wrapper API that manages Coolify deployments.
 
-**Current Version:** 1.6.0
+**Current Version:** 1.9.3
 
 ## Development Commands
 
@@ -63,6 +63,55 @@ try {
 }
 ```
 
+### Polling Mechanism Pattern (v1.9.0)
+
+Used for async operations (exec, db commands):
+
+```javascript
+async function pollForResult(applicationUuid, commandId, commandType, maxWaitSeconds = 120) {
+  const startTime = Date.now();
+  const pollInterval = 1000; // 1 second
+
+  while (true) {
+    const elapsed = (Date.now() - startTime) / 1000;
+
+    if (elapsed > maxWaitSeconds) {
+      throw new Error(`Command timed out after ${maxWaitSeconds} seconds`);
+    }
+
+    try {
+      const result = await api.getDbCommandResult(applicationUuid, commandType, commandId);
+
+      if (result.status === 'completed') {
+        return result;
+      }
+
+      if (result.status === 'failed') {
+        const errorMsg = result.result?.error || result.error || 'Command failed';
+        throw new Error(errorMsg);
+      }
+
+      // Still pending, wait and retry
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
+    } catch (error) {
+      // If error is not a 404 (command not found yet), rethrow
+      if (error.response?.status !== 404) {
+        throw error;
+      }
+      // 404 means command not processed yet, keep polling
+      await new Promise(resolve => setTimeout(resolve, pollInterval));
+    }
+  }
+}
+```
+
+**Key points:**
+- Universal polling endpoint: `/db/result/:commandId`
+- 1-second poll interval
+- 120-second default timeout
+- Handles 404 (command not ready yet) vs other errors
+- Returns result object with status, result, timestamps
+
 ## Authentication Flow
 
 ### Session Tokens (Primary Method)
@@ -110,14 +159,29 @@ SSE streaming implementation:
 **Commands:** `git connect/list/disconnect`
 **Flow:** Browser OAuth → CLI polls every 2s → Connection saved (AES-256-GCM encrypted)
 
-### Remote Execution (v1.6.0)
+### Remote Execution (v1.9.1)
 ```bash
 saac exec "npm run migrate"          # Execute command
 saac exec --history                  # View history
 ```
+**Implementation:** SSE command channel with polling mechanism
 **Security:** Command allowlist, dangerous pattern detection, rate limiting (30/5min)
+**Performance:** ~500ms average response time
 
-## API Endpoints (v1.6.0)
+### Database Management (v1.9.0)
+```bash
+saac db list                         # List database containers
+saac db sql "SELECT * FROM users"    # Execute SQL query (read-only)
+saac db sql "INSERT INTO..." --write # Write operation (requires flag)
+saac db sql "SELECT..." --db mydb    # Target specific database
+saac db redis GET mykey              # Execute Redis command
+saac db info                         # Show database connection info
+```
+**Implementation:** SSE command channel with universal polling endpoint
+**Security:** Read-only by default, --write flag for modifications, rate limiting (60/5min)
+**Performance:** ~1s average response time
+
+## API Endpoints (v1.9.0)
 
 ```
 POST   /api/v1/users/register
@@ -128,7 +192,16 @@ PATCH  /api/v1/applications/:uuid
 POST   /api/v1/applications/:uuid/deploy
 GET    /api/v1/applications/:uuid/logs         # ?follow=true for SSE
 GET    /api/v1/applications/:uuid/env/export
-POST   /api/v1/applications/:uuid/exec
+
+# Remote Execution (v1.9.1)
+POST   /api/v1/applications/:uuid/exec         # Queue command
+GET    /api/v1/applications/:uuid/db/result/:commandId  # Universal polling
+
+# Database Management (v1.9.0)
+GET    /api/v1/applications/:uuid/db/containers
+GET    /api/v1/applications/:uuid/db/info      # Instant response
+POST   /api/v1/applications/:uuid/db/sql       # Queue SQL query
+POST   /api/v1/applications/:uuid/db/redis     # Queue Redis command
 
 # OAuth (no /api/v1 prefix)
 GET    /oauth/authorize
@@ -142,7 +215,7 @@ GET    /oauth/poll/:session_id
 3. **delete message:** Use `app.name` not `result.application_name`
 4. **organization_id:** Added required `--org` flag to create command
 
-## Testing Methodology (v1.6.0)
+## Testing Methodology
 
 **Process:**
 1. Test ONE feature at a time
@@ -151,12 +224,29 @@ GET    /oauth/poll/:session_id
 4. Fix bugs immediately
 5. Move to next feature
 
-**35+ tests completed:**
+**Comprehensive tests completed:**
 - Authentication, auto-login, API keys
 - Git OAuth, application management
 - Environment/domain, logs, streaming
+- Database management (SQL queries, Redis commands)
+- Remote execution (allowed/blocked commands)
+- Error handling and user experience
 - Real app testing (golden-68-rekrytering-9jsq1e)
 
+**v1.9.0 Database Testing:**
+- Created test_users table with INSERT/SELECT operations
+- Tested PostgreSQL meta-queries (list databases, tables, schemas)
+- Tested Redis commands (PING, SET, GET, HGETALL)
+- Created new database (test_cli_db) with products table
+- Validated --write flag enforcement
+- Validated --db flag for targeting specific databases
+
+**v1.9.1/v1.9.2 Exec Testing:**
+- Tested allowed commands (npm, node, ls, cat, pwd)
+- Tested blocked commands (whoami, ps, kill)
+- Validated error messages and UX improvements
+- Confirmed ~500ms average response time
+
 ## Publishing Checklist
 
 1. Test all new features with live backend
@@ -166,8 +256,56 @@ GET    /oauth/poll/:session_id
 5. Git commit and push
 6. `npm publish --access public`
 
-## Version 1.6.0 Release Notes
+## Release Notes
 
+### Version 1.9.3 (Current)
+**Bug Fixes:**
+- Fixed SQL query crash when querying tables with text fields containing special characters
+- Backend now returns structured JSON format (`columns` and `rows` arrays) instead of raw CSV
+- Added fallback to CSV parsing for backward compatibility
+- Handles commas, newlines, and Swedish characters in text fields correctly
+
+### Version 1.9.2
+**Bug Fixes:**
+- Fixed exec error handling to use correct backend field (`data.error` not `data.message`)
+- Improved error messages for blocked commands
+- Updated allowed commands list to match backend implementation
+
+### Version 1.9.1
+**Improvements:**
+- Fixed `saac exec` to use SSE command channel with polling
+- Migrated from direct docker exec to daemon-based execution
+- Average response time improved to ~500ms (from 30s timeout)
+
+### Version 1.9.0
+**New Features:**
+- **Database Management Commands:**
+  - `saac db list` - List database containers (postgres, redis, etc.)
+  - `saac db sql <query>` - Execute SQL queries (read-only by default)
+  - `saac db redis <command>` - Execute Redis commands
+  - `saac db info` - Show database connection information
+- Read-only by default with `--write` flag for modifications
+- `--db` flag to target specific databases
+- Rate limiting: 60 queries per 5 minutes
+- Universal polling endpoint for all async operations
+
+**Implementation:**
+- Created `src/commands/db.js` (416 lines)
+- Added 5 new API client methods in `src/lib/api.js`
+- Polling mechanism with 1s interval, 120s timeout
+- Formatted table output for query results
+
+### Version 1.8.0
+**Improvements:**
+- Made deploy streaming the default behavior
+- Improved deploy command performance
+
+### Version 1.7.0
+**New Features:**
+- Deploy streaming support
+- No-cache deployment option
+
+### Version 1.6.0
 **New Features:**
 - SSE streaming for real-time logs (`--follow`)
 - Log type filtering (`--type access/runtime/build`)
@@ -184,6 +322,40 @@ GET    /oauth/poll/:session_id
 - `saac create` requires `--org` flag
 - `saac keys show` removed
 
+## Key Files & Structure
+
+```
+saac-cli/
+├── bin/
+│   └── saac.js                 # CLI entry point, all command definitions
+├── src/
+│   ├── commands/
+│   │   ├── auth.js            # login, logout, register, verify
+│   │   ├── create.js          # create applications
+│   │   ├── db.js              # database management (v1.9.0)
+│   │   ├── deploy.js          # deploy command
+│   │   ├── exec.js            # remote execution (v1.9.1)
+│   │   ├── git.js             # Git OAuth
+│   │   ├── keys.js            # API key management
+│   │   ├── logs.js            # log streaming (v1.6.0)
+│   │   └── ...                # other commands
+│   └── lib/
+│       ├── api.js             # Axios client, all API methods
+│       ├── config.js          # Config management, auth checking
+│       └── logger.js          # Formatted output utilities
+├── package.json               # Version, dependencies, bin script
+├── README.md                  # Public documentation
+└── CLAUDE.md                  # AI agent instructions (this file)
+```
+
+**Critical files for new features:**
+1. `bin/saac.js` - Add new command definitions
+2. `src/commands/<feature>.js` - Implement command logic
+3. `src/lib/api.js` - Add API client methods
+4. `package.json` - Update version number
+5. `README.md` - Document public-facing features
+6. `CLAUDE.md` - Update AI agent instructions
+
 ## Dependencies
 
 - axios, chalk, commander, conf, inquirer, ora, boxen, table, validator, dotenv, open, ws
@@ -215,8 +387,45 @@ GET    /oauth/poll/:session_id
 - Show FULL API keys when displayed (they're only shown once)
 - Same for session tokens during verification
 
+**Database command patterns:**
+- Always use `--write` flag for INSERT, UPDATE, DELETE, DROP, TRUNCATE
+- Use `--db` flag to target specific databases (defaults to env vars)
+- Format query results as tables using `table` package
+- Handle CSV output from backend (comma-separated rows)
+
+**Exec error handling (v1.9.2):**
+- 400 errors = command not allowed (show clear message with allowlist)
+- 408 errors = timeout (suggest increasing --timeout)
+- 429 errors = rate limit exceeded (30 commands per 5 minutes)
+- 503 errors = container not running
+- Backend error field is `data.error` (not `data.message`)
+- Show full backend error message with context
+
+## HIVE Collaboration
+
+**Agent Names:**
+- CLI Developer: `saac-saac-clitool-developer`
+- Backend Developer: `saac-owndockermachine-backend-developer`
+- Workspace Backend: `saac-workspace-backend-developer`
+- Orchestrator: `saac-orchestrator-backend-developer`
+
+**Collaboration Workflow:**
+1. Poll HIVE regularly when implementing new features
+2. Coordinate with backend developers for API changes
+3. Validate implementations with backend team
+4. Share knowledge and best practices with other agents
+5. Document all architectural decisions
+
+**Example Communication:**
+- Request API endpoint specifications
+- Confirm error response formats
+- Validate security patterns
+- Share implementation guides for other teams
+- Debug issues collaboratively
+
 ## MailHog & Testing
 
 - MailHog URL: https://mailhog.goryan.io
 - Default domain: `{subdomain}.startanaicompany.com`
 - Git server: https://git.startanaicompany.com
+- Test app: golden-68-rekrytering-9jsq1e

package/README.md

@@ -1472,17 +1472,19 @@ Run one-off commands inside your container without opening an interactive shell.
 Execute a single command in the remote container.
 
 ```bash
-# Run command
+# Run npm commands
 saac exec "npm run db:migrate"
+saac exec "npm test"
+saac exec "npm run build"
 
-# Check Node.js version
+# Check versions
 saac exec "node --version"
+saac exec "npm --version"
 
-# View environment variables
-saac exec "printenv | grep NODE"
-
-# Check running processes
-saac exec "ps aux"
+# File operations
+saac exec "ls -la"
+saac exec "cat package.json"
+saac exec "pwd"
 
 # Custom working directory
 saac exec "npm test" --workdir /app/src
@@ -1495,6 +1497,34 @@ saac exec "npm run build" --timeout 300
 - `--workdir <path>` - Working directory (default: `/app`)
 - `--timeout <seconds>` - Timeout in seconds (default: 30, max: 300)
 
+**Security & Command Allowlist:**
+
+For security, only specific commands are allowed. Commands are executed via the SSE command channel with ~500ms response time.
+
+**Allowed Commands:**
+- **Node.js:** npm, node, npx, yarn, pnpm
+- **Python:** python, python3, pip, pip3, poetry
+- **Ruby:** bundle, rake, rails, ruby
+- **Shell:** sh, bash, echo, cat, ls, pwd, env
+- **Database:** psql, mysql, mongosh
+- **Build:** go, cargo, make, cmake
+
+**Blocked for Security:**
+- System commands: `whoami`, `ps`, `top`, `kill`
+- Destructive operations: `rm`, `chmod`, `chown`
+- Advanced shell features: pipes (`|`), redirects (`>`), command substitution
+
+**Rate Limit:** 60 commands per 5 minutes per user
+
+If you try a blocked command, you'll see a clear error message:
+```
+✖ Command not allowed
+
+✗ This command is blocked for security reasons
+
+⚠ Command 'whoami' is not in allowlist. Allowed commands: ...
+```
+
 **Example output:**
 ```bash
 $ saac exec "npm run db:migrate"
@@ -2451,7 +2481,8 @@ saac shell
 **Workaround:** Use `saac exec` for one-off commands:
 ```bash
 saac exec "npm run migrate"
-saac exec "ps aux"
+saac exec "node --version"
+saac exec "ls -la"
 ```
 
 ### General Debugging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startanaicompany/cli",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Official CLI for StartAnAiCompany.com - Deploy AI recruitment sites with ease",
   "main": "src/index.js",
   "bin": {

package/src/commands/db.js

@@ -166,8 +166,21 @@ async function sql(query, options) {
       spin.succeed('Query executed');
       logger.newline();
 
-      if (result.result && result.result.output) {
-        // Display CSV output as table
+      if (result.result && result.result.format === 'json') {
+        // New format: structured JSON with columns and rows
+        const { columns, rows } = result.result;
+
+        if (columns && rows && rows.length > 0) {
+          // Build table data with header row
+          const tableData = [columns, ...rows];
+          console.log(table(tableData));
+          logger.newline();
+          logger.info(`Rows returned: ${rows.length}`);
+        } else {
+          logger.info('Query returned no results');
+        }
+      } else if (result.result && result.result.output) {
+        // Fallback: old CSV format (if daemon parsing failed)
         const csvData = result.result.output;
         const rows = csvData.trim().split('\n').map(row => row.split(','));
 

package/src/commands/exec.js

@@ -111,27 +111,36 @@ async function exec(command, options = {}) {
 
       spin.succeed('Command executed');
     } catch (error) {
-      spin.fail('Command execution failed');
+      spin.fail('Command not allowed');
 
       if (error.response?.status === 400) {
-        const data = error.response.data;
+        const data = error.response.data || {};
         logger.newline();
 
-        if (data.error === 'VALIDATION_ERROR') {
-          logger.error('Command validation failed');
+        // Show clear "command not allowed" message for all 400 errors
+        logger.error('This command is blocked for security reasons');
+
+        // Show backend error message if available (note: field is 'error', not 'message')
+        if (data.error) {
           logger.newline();
-          logger.warn(data.message);
-
-          if (data.message.includes('not in allowlist')) {
-            logger.newline();
-            logger.info('Allowed commands include:');
-            logger.log('  Node.js: npm, node, npx, yarn, pnpm');
-            logger.log('  Python: python, python3, pip, poetry');
-            logger.log('  Ruby: bundle, rake, rails');
-            logger.log('  Shell: sh, bash, echo, cat, ls, pwd');
-            logger.log('  Database: psql, mysql, mongosh');
-          }
+          logger.warn(data.error);
         }
+
+        logger.newline();
+        logger.info('Allowed commands include:');
+        logger.log('  Node.js: npm, node, npx, yarn, pnpm');
+        logger.log('  Python: python, python3, pip, poetry');
+        logger.log('  Ruby: bundle, rake, rails, ruby');
+        logger.log('  Shell: sh, bash, echo, cat, ls, pwd, env');
+        logger.log('  Database: psql, mysql, mongosh');
+        logger.log('  Build: go, cargo, make, cmake');
+        logger.newline();
+        logger.info('Blocked for security:');
+        logger.log('  System commands: whoami, ps, top, kill');
+        logger.log('  Destructive operations: rm, chmod, chown');
+        logger.log('  Advanced shell features: pipes (|), redirects (>), command substitution');
+
+        process.exit(1);
       } else if (error.response?.status === 408) {
         logger.newline();
         logger.error('Command execution timed out');