@startanaicompany/cli 1.4.16 → 1.4.17

package/CLAUDE.md

@@ -275,6 +275,71 @@ saac create web -s web -r git@git... -t abc123 \
 - Saves project config to `.saac/config.json` after successful creation
 - Displays next steps and useful commands
 
+**Deployment Behavior (NEW):**
+
+The `create` command now **waits for the initial deployment to complete** (up to 5 minutes) before returning.
+
+**Response Time:**
+- Typical: 30-120 seconds
+- Maximum: 5 minutes (timeout)
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "coolify_app_uuid": "...",
+  "app_name": "my-app",
+  "domain": "https://myapp.startanaicompany.com",
+  "deployment_status": "finished",
+  "deployment_uuid": "...",
+  "git_branch": "master"
+}
+```
+
+**Failure Response (HTTP 200 with success: false):**
+```json
+{
+  "success": false,
+  "coolify_app_uuid": "...",
+  "app_name": "my-app",
+  "deployment_status": "failed",
+  "message": "Port 8080 is already in use. Remove host port bindings...",
+  "errors": [
+    {
+      "type": "PORT_CONFLICT",
+      "message": "Port 8080 is already in use...",
+      "detail": "Bind for 0.0.0.0:8080 failed..."
+    }
+  ],
+  "relevant_logs": [...],
+  "last_logs": [...]
+}
+```
+
+**Error Types:**
+- `PORT_CONFLICT` - Host port binding conflict in docker-compose.yml
+- `BUILD_FAILED` - Build process returned non-zero exit code
+- `TIMEOUT` - Deployment didn't complete in 5 minutes
+- `UNKNOWN` - Generic deployment failure
+
+**Important Notes:**
+1. **Application is created even if deployment fails** - the UUID is saved to `.saac/config.json`
+2. Failed deployments return HTTP 200 (not 4xx) with `success: false`
+3. CLI must check the `success` field, not just HTTP status code
+4. Detailed error information is displayed with actionable advice
+5. User can fix the issue and run `saac deploy` to retry
+
+**Error Display:**
+The CLI displays comprehensive error information:
+- Error summary message
+- Structured error details with types
+- Relevant error logs (filtered)
+- Last log lines for context
+- Actionable advice based on error type:
+  - `PORT_CONFLICT`: Remove host port bindings from docker-compose.yml
+  - `BUILD_FAILED`: Check Dockerfile, run `docker build .` locally
+  - `TIMEOUT`: Check `saac status` and `saac logs`, may still be running
+
 ### Update Command Implementation
 
 The `update` command allows modifying application configuration after deployment using `PATCH /api/v1/applications/:uuid`.
@@ -373,7 +438,7 @@ saac git disconnect git.startanaicompany.com
 
 ### Deploy Command Implementation
 
-The `deploy` command triggers deployment for the current application.
+The `deploy` command triggers deployment and **waits for completion** (up to 5 minutes).
 
 **Usage:**
 ```bash
@@ -385,13 +450,57 @@ saac deploy --force
 1. Validates authentication (session token not expired)
 2. Checks for project config (`.saac/config.json`)
 3. Makes POST request to `/api/v1/applications/:uuid/deploy`
-4. Displays deployment status and deployment ID
-5. Shows command to follow logs: `saac logs --follow`
+4. **Waits for deployment to complete** (up to 5 minutes)
+5. Displays deployment status with detailed error information on failure
+
+**Response Time:**
+- Typical: 30-120 seconds
+- Maximum: 5 minutes (timeout)
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "status": "finished",
+  "deployment_uuid": "...",
+  "git_branch": "master",
+  "domain": "https://myapp.startanaicompany.com",
+  "traefik_status": "queued"
+}
+```
+
+**Failure Response:**
+```json
+{
+  "success": false,
+  "status": "failed",
+  "message": "Build failed with exit code 1",
+  "errors": [
+    {
+      "type": "BUILD_FAILED",
+      "message": "Build failed with exit code 1",
+      "detail": "npm ERR! code ELIFECYCLE..."
+    }
+  ],
+  "relevant_logs": [...],
+  "last_logs": [...]
+}
+```
 
-**Response Fields:**
-- `status` - Application status after deployment triggered
-- `domain` - Application domain (if available)
-- `deployment_id` - Unique ID for this deployment
+**Error Types:**
+- `PORT_CONFLICT` - Host port binding conflict
+- `BUILD_FAILED` - Build process failed
+- `TIMEOUT` - Deployment didn't complete in 5 minutes
+- `UNKNOWN` - Generic failure
+
+**Error Display:**
+The CLI displays:
+1. Error summary message
+2. Structured error details with types
+3. Relevant logs (filtered error logs)
+4. Last 5 log lines for context
+5. Actionable advice based on error type
+6. Suggestion to view full logs with `saac logs --follow`
 
 **Note:** The `--force` flag is defined in the CLI but not currently used by the API.
 
@@ -588,7 +697,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.16
+## Current Status - Version 1.4.17
 
 ### Completed Features
 
@@ -808,4 +917,4 @@ Before publishing to npm:
 - `dotenv` - Environment variables
 - `open` - Open browser for OAuth (v8.4.2 for compatibility with chalk v4)
 
-**Version:** 1.4.16 (current)
+**Version:** 1.4.17 (current)

package/package.json

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

package/src/commands/create.js

@@ -8,6 +8,7 @@ const logger = require('../lib/logger');
 const oauth = require('../lib/oauth');
 const inquirer = require('inquirer');
 const { execSync } = require('child_process');
+const errorDisplay = require('../lib/errorDisplay');
 
 async function create(name, options) {
   try {
@@ -281,14 +282,12 @@ async function create(name, options) {
 
     logger.newline();
 
-    const spin = logger.spinner('Creating application...').start();
+    const spin = logger.spinner('Creating application and deploying (this may take up to 5 minutes)...').start();
 
     try {
       const result = await api.createApplication(appData);
 
-      spin.succeed('Application created successfully!');
-
-      // Save project configuration
+      // Always save project configuration (even if deployment failed)
       saveProjectConfig({
         applicationUuid: result.coolify_app_uuid,
         applicationName: result.app_name,
@@ -297,13 +296,35 @@ async function create(name, options) {
         gitRepository: appData.git_repository,
       });
 
+      // Check if deployment failed
+      if (result.success === false) {
+        spin.fail('Deployment failed');
+
+        // Display detailed error information
+        errorDisplay.displayDeploymentError(result, logger);
+
+        // Show recovery instructions
+        errorDisplay.displayCreateRecoveryInstructions(result, logger);
+
+        process.exit(1);
+      }
+
+      // SUCCESS: Application created and deployed
+      spin.succeed('Application created and deployed successfully!');
+
       logger.newline();
-      logger.success('Application created!');
+      logger.success('Your application is live!');
       logger.newline();
       logger.field('Name', result.app_name);
       logger.field('Domain', result.domain);
       logger.field('UUID', result.coolify_app_uuid);
-      logger.field('Status', result.deployment_status);
+      logger.field('Status', result.deployment_status || 'finished');
+      if (result.git_branch) {
+        logger.field('Branch', result.git_branch);
+      }
+      if (result.deployment_uuid) {
+        logger.field('Deployment ID', result.deployment_uuid);
+      }
       logger.newline();
 
       // Show next steps

package/src/commands/deploy.js

@@ -5,6 +5,7 @@
 const api = require('../lib/api');
 const { getProjectConfig, isAuthenticated } = require('../lib/config');
 const logger = require('../lib/logger');
+const errorDisplay = require('../lib/errorDisplay');
 
 async function deploy(options) {
   try {
@@ -25,30 +26,62 @@ async function deploy(options) {
     const { applicationUuid, applicationName } = projectConfig;
 
     logger.section(`Deploying ${applicationName}`);
+    logger.newline();
 
-    const spin = logger.spinner('Triggering deployment...').start();
+    const spin = logger.spinner('Deploying application (waiting for completion, up to 5 minutes)...').start();
 
     try {
       const result = await api.deployApplication(applicationUuid);
 
-      spin.succeed('Deployment triggered!');
+      // Check if deployment failed
+      if (result.success === false) {
+        spin.fail('Deployment failed');
+
+        // Display detailed error information
+        errorDisplay.displayDeploymentError(result, logger);
+
+        // Handle timeout specifically
+        if (result.status === 'timeout') {
+          errorDisplay.displayTimeoutInstructions(logger);
+        }
+
+        process.exit(1);
+      }
+
+      // SUCCESS: Deployment completed
+      spin.succeed('Deployment completed successfully!');
 
       logger.newline();
-      logger.success('Deployment started successfully');
+      logger.success('Your application has been deployed!');
       logger.newline();
       logger.field('Application', applicationName);
       logger.field('Status', result.status);
+      if (result.git_branch) {
+        logger.field('Branch', result.git_branch);
+      }
       if (result.domain) {
         logger.field('Domain', result.domain);
       }
-      logger.field('Deployment ID', result.deployment_id);
+      if (result.deployment_uuid || result.deployment_id) {
+        logger.field('Deployment ID', result.deployment_uuid || result.deployment_id);
+      }
       logger.newline();
-      logger.info(
-        `View logs with: ${logger.chalk.yellow('saac logs --follow')}`
-      );
+
+      // Show Traefik status if present
+      if (result.traefik_status === 'queued') {
+        logger.info('Routing configuration is being applied (may take a few seconds)');
+        logger.newline();
+      } else if (result.traefik_status === 'failed') {
+        logger.warn('Routing configuration failed - application may not be accessible');
+        logger.newline();
+      }
+
+      logger.info('Useful commands:');
+      logger.log(`  saac logs --follow       View live deployment logs`);
+      logger.log(`  saac status              Check application status`);
 
     } catch (error) {
-      spin.fail('Deployment failed');
+      spin.fail('Deployment request failed');
       throw error;
     }
   } catch (error) {

package/src/lib/api.js

@@ -9,8 +9,9 @@ const pkg = require('../../package.json');
 
 /**
  * Create axios instance with base configuration
+ * @param {number} timeout - Timeout in milliseconds (default: 30000)
  */
-function createClient() {
+function createClient(timeout = 30000) {
   const user = getUser();
   const envApiKey = process.env.SAAC_API_KEY; // For CI/CD
 
@@ -33,7 +34,7 @@ function createClient() {
 
   return axios.create({
     baseURL: getApiUrl(),
-    timeout: 30000,
+    timeout: timeout,
     headers,
   });
 }
@@ -88,9 +89,11 @@ async function getUserInfo() {
 
 /**
  * Create a new application
+ * Note: This waits for deployment to complete (up to 5 minutes)
  */
 async function createApplication(appData) {
-  const client = createClient();
+  // Use 5-minute timeout for deployment waiting
+  const client = createClient(300000); // 5 minutes
   const response = await client.post('/applications', appData);
   return response.data;
 }
@@ -115,9 +118,11 @@ async function getApplication(uuid) {
 
 /**
  * Deploy application
+ * Note: This waits for deployment to complete (up to 5 minutes)
  */
 async function deployApplication(uuid) {
-  const client = createClient();
+  // Use 5-minute timeout for deployment waiting
+  const client = createClient(300000); // 5 minutes
   const response = await client.post(`/applications/${uuid}/deploy`);
   return response.data;
 }

package/src/lib/errorDisplay.js

@@ -0,0 +1,170 @@
+/**
+ * Error Display Utilities
+ * Formats and displays deployment errors with actionable advice
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Get actionable advice for specific error types
+ */
+function getErrorAdvice(errorType) {
+  const advice = {
+    PORT_CONFLICT: [
+      'Fix: Remove host port bindings from your docker-compose.yml',
+      '     Change "8080:8080" to just "8080"',
+      '     Traefik will handle external routing automatically',
+    ],
+    BUILD_FAILED: [
+      'Fix: Check your Dockerfile and build configuration',
+      '     Run "docker build ." locally to debug',
+      '     Verify all dependencies are properly specified',
+    ],
+    TIMEOUT: [
+      'Note: Deployment may still be running in the background',
+      '      Check status with: saac status',
+      '      View logs with: saac logs --follow',
+    ],
+    UNKNOWN: [
+      'Tip: Check the deployment logs for more details',
+      '     Run: saac logs --follow',
+    ],
+    PARSE_ERROR: [
+      'Note: Could not parse deployment logs',
+      '      Contact support if this persists',
+    ],
+  };
+
+  return advice[errorType] || advice.UNKNOWN;
+}
+
+/**
+ * Format log lines for display
+ */
+function formatLogs(logs, maxLines = 10) {
+  if (!logs || logs.length === 0) {
+    return [];
+  }
+
+  // If logs is an array of objects with 'output' field
+  if (logs[0] && typeof logs[0] === 'object' && logs[0].output) {
+    return logs.slice(-maxLines).map(log => log.output);
+  }
+
+  // If logs is an array of strings
+  return logs.slice(-maxLines);
+}
+
+/**
+ * Display detailed deployment error information
+ */
+function displayDeploymentError(result, logger) {
+  logger.newline();
+  logger.error(`Deployment Error: ${result.message || 'Deployment failed'}`);
+  logger.newline();
+
+  // Display deployment info
+  if (result.deployment_status || result.status) {
+    logger.field('Status', result.deployment_status || result.status);
+  }
+  if (result.git_branch) {
+    logger.field('Branch', result.git_branch);
+  }
+  if (result.deployment_uuid) {
+    logger.field('Deployment ID', result.deployment_uuid);
+  }
+
+  logger.newline();
+
+  // Display structured errors
+  if (result.errors && result.errors.length > 0) {
+    logger.info('Error Details:');
+    result.errors.forEach(err => {
+      logger.log(`  ${chalk.yellow(`[${err.type}]`)} ${err.message}`);
+      if (err.detail) {
+        const detailLines = err.detail.split('\n').slice(0, 3); // First 3 lines
+        detailLines.forEach(line => {
+          logger.log(`    ${chalk.gray(line)}`);
+        });
+      }
+    });
+    logger.newline();
+
+    // Display actionable advice for the first error
+    const firstError = result.errors[0];
+    if (firstError && firstError.type) {
+      const advice = getErrorAdvice(firstError.type);
+      if (advice && advice.length > 0) {
+        logger.info('Suggested Fix:');
+        advice.forEach(line => {
+          logger.log(`  ${chalk.cyan(line)}`);
+        });
+        logger.newline();
+      }
+    }
+  }
+
+  // Display relevant logs (filtered error logs)
+  if (result.relevant_logs && result.relevant_logs.length > 0) {
+    logger.info('Relevant Logs:');
+    const logLines = formatLogs(result.relevant_logs, 5);
+    logLines.forEach(line => {
+      logger.log(`  ${chalk.gray(line)}`);
+    });
+    logger.newline();
+  }
+
+  // Display last logs (context)
+  if (result.last_logs && result.last_logs.length > 0) {
+    logger.info('Recent Log Output:');
+    const logLines = formatLogs(result.last_logs, 5);
+    logLines.forEach(line => {
+      logger.log(`  ${chalk.gray(line)}`);
+    });
+    logger.newline();
+  }
+
+  // Suggest viewing full logs
+  if (result.coolify_app_uuid || result.deployment_uuid) {
+    const uuid = result.coolify_app_uuid || result.deployment_uuid;
+    logger.info('View full logs:');
+    logger.log(`  ${chalk.yellow('saac logs --follow')}`);
+    logger.newline();
+  }
+}
+
+/**
+ * Display recovery instructions after failed create
+ */
+function displayCreateRecoveryInstructions(result, logger) {
+  if (result.coolify_app_uuid) {
+    logger.warn(`Application "${result.app_name}" was created but deployment failed.`);
+    logger.info('Fix the issue in your repository, then redeploy:');
+    logger.log(`  ${chalk.yellow('saac deploy')}`);
+    logger.newline();
+    logger.info('Or delete and recreate:');
+    logger.log(`  ${chalk.yellow(`saac delete ${result.coolify_app_uuid}`)}`);
+  }
+}
+
+/**
+ * Display timeout-specific instructions
+ */
+function displayTimeoutInstructions(logger) {
+  logger.warn('Deployment timed out after 5 minutes');
+  logger.newline();
+  logger.info('The deployment may still be running in the background.');
+  logger.info('Check the status:');
+  logger.log(`  ${chalk.yellow('saac status')}`);
+  logger.newline();
+  logger.info('Or view live logs:');
+  logger.log(`  ${chalk.yellow('saac logs --follow')}`);
+}
+
+module.exports = {
+  getErrorAdvice,
+  formatLogs,
+  displayDeploymentError,
+  displayCreateRecoveryInstructions,
+  displayTimeoutInstructions,
+};