abapgit-agent 1.8.5 → 1.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.8.5",
+  "version": "1.8.6",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [

package/src/commands/import.js

@@ -2,6 +2,14 @@
  * Import command - Import existing objects from package to git repository
  */
 
+const {
+  startBackgroundJob,
+  pollForCompletion,
+  displayProgress,
+  formatTimestamp,
+  calculateTimeSpent
+} = require('../utils/backgroundJobPoller');
+
 module.exports = {
   name: 'import',
   description: 'Import existing objects from package to git repository',
@@ -9,9 +17,10 @@ module.exports = {
   requiresVersionCheck: true,
 
   async execute(args, context) {
-    const { loadConfig, gitUtils, AbapHttp } = context;
+    try {
+      const { loadConfig, gitUtils, AbapHttp } = context;
 
-    // Show help if requested
+      // Show help if requested
     const helpIndex = args.findIndex(a => a === '--help' || a === '-h');
     if (helpIndex !== -1) {
       console.log(`
@@ -22,6 +31,9 @@ Description:
   Import existing objects from package to git repository.
   Uses the git remote URL to find the abapGit online repository.
 
+  This command runs asynchronously using a background job and displays
+  real-time progress updates.
+
 Prerequisites:
   - Run "abapgit-agent create" first or create repository in abapGit UI
   - Package must have objects to import
@@ -51,7 +63,7 @@ Examples:
       commitMessage = args[messageArgIndex + 1];
     }
 
-    console.log(`\n📦 Importing objects to git repository`);
+    console.log(`\n📦 Starting import job`);
     console.log(`   URL: ${repoUrl}`);
     if (commitMessage) {
       console.log(`   Message: ${commitMessage}`);
@@ -76,23 +88,69 @@ Examples:
       data.password = config.gitPassword;
     }
 
-    const result = await http.post('/sap/bc/z_abapgit_agent/import', data, { csrfToken });
+    // Step 1: Start the background job
+    const endpoint = '/sap/bc/z_abapgit_agent/import';
+    const jobInfo = await startBackgroundJob(http, endpoint, data, csrfToken);
 
-    console.log('\n');
+    console.log(`✅ Job started: ${jobInfo.jobNumber}`);
+    console.log('');
 
-    // Handle uppercase keys from ABAP
-    const success = result.SUCCESS || result.success;
-    const filesStaged = result.FILES_STAGED || result.files_staged;
-    const abapCommitMessage = result.COMMIT_MESSAGE || result.commit_message;
-    const error = result.ERROR || result.error;
+    // Step 2: Poll for completion with progress updates
+    const finalResult = await pollForCompletion(http, endpoint, jobInfo.jobNumber, {
+      pollInterval: 2000,
+      maxAttempts: 300,
+      onProgress: (progress, message) => {
+        displayProgress(progress, message);
+      }
+    });
 
-    if (success === 'X' || success === true) {
-      console.log(`✅ Objects imported successfully!`);
-      console.log(`   Files staged: ${filesStaged}`);
-      console.log(`   Commit: ${commitMessage || abapCommitMessage}`);
+    // Step 3: Show final result
+    console.log('\n');
+
+    if (finalResult.status === 'completed' && finalResult.result) {
+      // Parse result JSON string
+      let resultData;
+      try {
+        if (typeof finalResult.result === 'string') {
+          resultData = JSON.parse(finalResult.result);
+        } else {
+          resultData = finalResult.result;
+        }
+      } catch (e) {
+        resultData = { filesStaged: 'unknown', commitMessage: commitMessage };
+      }
+
+      console.log(`✅ Import completed successfully!`);
+      console.log(`   Files staged: ${resultData.filesStaged || resultData.FILES_STAGED || 'unknown'}`);
+      console.log(`   Commit: ${resultData.commitMessage || resultData.COMMIT_MESSAGE || commitMessage || 'Initial import'}`);
+      console.log(``);
+
+      // Calculate time spent
+      if (finalResult.startedAt && finalResult.completedAt) {
+        const timeSpent = calculateTimeSpent(finalResult.startedAt, finalResult.completedAt);
+        console.log(`⏱️  Time spent: ${timeSpent}`);
+      }
+
+      console.log(`📈 Stats:`);
+      console.log(`   Job number: ${jobInfo.jobNumber}`);
+      if (finalResult.startedAt) {
+        console.log(`   Started: ${formatTimestamp(finalResult.startedAt)}`);
+      }
+      if (finalResult.completedAt) {
+        console.log(`   Completed: ${formatTimestamp(finalResult.completedAt)}`);
+      }
     } else {
       console.log(`❌ Import failed`);
-      console.log(`   Error: ${error || 'Unknown error'}`);
+      console.log(`   Status: ${finalResult.status}`);
+      process.exit(1);
+    }
+    } catch (error) {
+      console.error('\n❌ Error during import:');
+      console.error(`   ${error.message || error}`);
+      if (error.response) {
+        console.error(`   HTTP Status: ${error.response.status}`);
+        console.error(`   Response: ${JSON.stringify(error.response.data)}`);
+      }
       process.exit(1);
     }
   }

package/src/utils/backgroundJobPoller.README.md

@@ -0,0 +1,218 @@
+# Background Job Polling Utility
+
+Generic utility for commands that run as ABAP background jobs with progress reporting.
+
+## Overview
+
+This utility provides a reusable pattern for CLI commands that need to:
+1. Start an ABAP background job
+2. Poll for job status with real-time progress updates
+3. Display progress bars and final results
+
+## Usage
+
+### Basic Example
+
+```javascript
+const {
+  startBackgroundJob,
+  pollForCompletion,
+  displayProgress,
+  formatTimestamp,
+  calculateTimeSpent
+} = require('../utils/backgroundJobPoller');
+
+// In your command's execute() method:
+async execute(args, context) {
+  const { AbapHttp, loadConfig } = context;
+  const config = loadConfig();
+  const http = new AbapHttp(config);
+  const csrfToken = await http.fetchCsrfToken();
+
+  // 1. Start background job
+  const endpoint = '/sap/bc/z_abapgit_agent/mycommand';
+  const jobInfo = await startBackgroundJob(http, endpoint, data, csrfToken);
+
+  console.log(`✅ Job started: ${jobInfo.jobNumber}`);
+
+  // 2. Poll for completion
+  const finalResult = await pollForCompletion(http, endpoint, jobInfo.jobNumber, {
+    pollInterval: 2000,
+    maxAttempts: 300,
+    onProgress: (progress, message) => {
+      displayProgress(progress, message);
+    }
+  });
+
+  // 3. Show final result
+  console.log('\n');
+  if (finalResult.status === 'completed') {
+    console.log(`✅ Command completed successfully!`);
+
+    const timeSpent = calculateTimeSpent(finalResult.startedAt, finalResult.completedAt);
+    console.log(`⏱️  Time spent: ${timeSpent}`);
+    console.log(`   Started: ${formatTimestamp(finalResult.startedAt)}`);
+    console.log(`   Completed: ${formatTimestamp(finalResult.completedAt)}`);
+  }
+}
+```
+
+## API Reference
+
+### `startBackgroundJob(http, endpoint, data, csrfToken)`
+
+Start a background job.
+
+**Parameters:**
+- `http` - AbapHttp instance
+- `endpoint` - API endpoint (e.g., `/sap/bc/z_abapgit_agent/import`)
+- `data` - Request data object
+- `csrfToken` - CSRF token from `http.fetchCsrfToken()`
+
+**Returns:** `{ jobNumber, jobName, status }`
+
+**Throws:** Error if job failed to start
+
+### `pollForCompletion(http, endpoint, jobNumber, options)`
+
+Poll for job completion with progress updates.
+
+**Parameters:**
+- `http` - AbapHttp instance
+- `endpoint` - Status endpoint (same as start endpoint)
+- `jobNumber` - Job number from `startBackgroundJob()`
+- `options` - Polling options:
+  - `pollInterval` - Milliseconds between polls (default: 2000)
+  - `maxAttempts` - Max polling attempts (default: 300 = 10 minutes)
+  - `onProgress(progress, message)` - Callback for progress updates
+
+**Returns:**
+```javascript
+{
+  status: 'completed',
+  result: '{"filesStaged": 100}',  // JSON string or object
+  startedAt: '20260305103045',
+  completedAt: '20260305103520',
+  jobNumber: '12345678',
+  jobName: 'IMPORT_20260305103045'
+}
+```
+
+**Throws:** Error if job fails or times out
+
+### `displayProgress(progress, message, options)`
+
+Display progress bar in console.
+
+**Parameters:**
+- `progress` - Progress percentage (0-100)
+- `message` - Progress message
+- `options` - Display options:
+  - `barWidth` - Width of progress bar (default: 30)
+  - `showPercentage` - Show percentage number (default: false)
+
+**Example Output:**
+```
+[===============               ] Staging files (1250 of 3701)
+```
+
+### `formatTimestamp(timestamp)`
+
+Format ABAP timestamp to readable local format.
+
+**Parameters:**
+- `timestamp` - ABAP timestamp (YYYYMMDDHHMMSS)
+
+**Returns:** Formatted timestamp (YYYY-MM-DD HH:MM:SS)
+
+**Example:**
+```javascript
+formatTimestamp('20260305103045')
+// => "2026-03-05 10:30:45"
+```
+
+### `calculateTimeSpent(startTimestamp, endTimestamp)`
+
+Calculate time difference between two ABAP timestamps.
+
+**Parameters:**
+- `startTimestamp` - Start timestamp (YYYYMMDDHHMMSS)
+- `endTimestamp` - End timestamp (YYYYMMDDHHMMSS)
+
+**Returns:** Human-readable duration
+
+**Examples:**
+```javascript
+calculateTimeSpent('20260305103000', '20260305103015')
+// => "15 seconds"
+
+calculateTimeSpent('20260305103000', '20260305103145')
+// => "1 minute 45 seconds"
+
+calculateTimeSpent('20260305103000', '20260305123015')
+// => "2 hours 0 minutes"
+```
+
+## ABAP Requirements
+
+For a command to use this utility, the ABAP side must:
+
+1. **Implement `zif_abgagt_progressable` interface** on the command class:
+   ```abap
+   CLASS zcl_abgagt_command_mycommand DEFINITION.
+     PUBLIC SECTION.
+       INTERFACES zif_abgagt_command.
+       INTERFACES zif_abgagt_progressable.  " ← Add this
+   ENDCLASS.
+   ```
+
+2. **Raise progress events** during execution:
+   ```abap
+   METHOD zif_abgagt_progressable~execute_with_progress.
+     " Update progress
+     RAISE EVENT zif_abgagt_progressable~progress_update
+       EXPORTING
+         iv_stage    = 'PROCESSING'
+         iv_message  = 'Processing items'
+         iv_progress = 50
+         iv_current  = 500
+         iv_total    = 1000.
+   ENDMETHOD.
+   ```
+
+3. **Return structured result** in JSON format:
+   ```abap
+   " Final result
+   ls_result = VALUE #(
+     success = abap_true
+     items_processed = 1000
+     message = 'Processing completed'
+   ).
+   ```
+
+The background job infrastructure will automatically:
+- ✅ Detect the `progressable` interface
+- ✅ Schedule the command as a background job
+- ✅ Listen to progress events and update status
+- ✅ Return HTTP 202 Accepted with job number
+- ✅ Support status polling via GET endpoint
+
+## Example Commands Using This Utility
+
+- **import** - Import objects from ABAP package to git (already implemented)
+- **pull** - Could be enhanced to support async execution for large file sets
+- **inspect** - Could be enhanced for package-wide inspection
+
+## Testing
+
+Unit tests are available in `tests/unit/backgroundJobPoller.test.js`:
+
+```bash
+npm test -- tests/unit/backgroundJobPoller.test.js
+```
+
+## See Also
+
+- [Background Job Architecture](../../docs/architecture/README.md) - Complete architecture documentation
+- [Import Command](../commands/import.js) - Reference implementation
+- [API Documentation](../../API.md) - REST API for async commands

package/src/utils/backgroundJobPoller.js

@@ -0,0 +1,251 @@
+/**
+ * Generic background job polling utility
+ *
+ * Provides reusable functions for commands that run as background jobs
+ * with progress reporting.
+ */
+
+/**
+ * Start a background job for a command
+ *
+ * @param {Object} http - AbapHttp instance
+ * @param {string} endpoint - API endpoint (e.g., '/sap/bc/z_abapgit_agent/import')
+ * @param {Object} data - Request data
+ * @param {Object} csrfToken - CSRF token
+ * @returns {Object} Job info with jobNumber, jobName
+ * @throws {Error} If job failed to start
+ */
+async function startBackgroundJob(http, endpoint, data, csrfToken) {
+  const result = await http.post(endpoint, data, { csrfToken });
+
+  const success = result.SUCCESS || result.success;
+  const jobNumber = result.JOB_NUMBER || result.jobNumber;
+  const jobName = result.JOB_NAME || result.jobName;
+  const error = result.ERROR || result.error;
+
+  if (success !== 'X' && success !== true) {
+    throw new Error(error || 'Failed to start background job');
+  }
+
+  return {
+    jobNumber,
+    jobName,
+    status: result.STATUS || result.status
+  };
+}
+
+/**
+ * Poll for job completion with progress updates
+ *
+ * @param {Object} http - AbapHttp instance
+ * @param {string} endpoint - Status endpoint (e.g., '/sap/bc/z_abapgit_agent/import')
+ * @param {string} jobNumber - Job number to poll
+ * @param {Object} options - Polling options
+ * @param {number} options.pollInterval - Milliseconds between polls (default: 2000)
+ * @param {number} options.maxAttempts - Max polling attempts (default: 300 = 10 minutes)
+ * @param {Function} options.onProgress - Callback for progress updates (progress, message)
+ * @returns {Object} Final job result
+ * @throws {Error} If job fails or times out
+ */
+async function pollForCompletion(http, endpoint, jobNumber, options = {}) {
+  const {
+    pollInterval = 2000,
+    maxAttempts = 300,  // 10 minutes with 2-second intervals
+    onProgress = () => {}
+  } = options;
+
+  let status = 'running';
+  let lastProgress = -1;
+  let pollCount = 0;
+
+  while (status === 'running' || status === 'scheduled') {
+    // Wait before polling (except first time)
+    if (pollCount > 0) {
+      await sleep(pollInterval);
+    }
+    pollCount++;
+
+    // Check timeout
+    if (pollCount > maxAttempts) {
+      throw new Error(`Job polling timeout after ${maxAttempts * pollInterval / 1000} seconds`);
+    }
+
+    // Get status
+    const statusResult = await http.get(`${endpoint}?jobNumber=${jobNumber}`);
+
+    status = statusResult.STATUS || statusResult.status;
+    const progress = statusResult.PROGRESS || statusResult.progress || 0;
+    const message = statusResult.MESSAGE || statusResult.message || '';
+    const errorMessage = statusResult.ERROR_MESSAGE || statusResult.errorMessage;
+
+    // Handle job not found
+    if (statusResult.ERROR || statusResult.error) {
+      throw new Error(statusResult.ERROR || statusResult.error);
+    }
+
+    // Show progress if changed
+    if (progress !== lastProgress) {
+      onProgress(progress, message);
+      lastProgress = progress;
+    }
+
+    // Handle error status
+    if (status === 'error') {
+      throw new Error(errorMessage || 'Job failed with unknown error');
+    }
+  }
+
+  // Get final result
+  const finalResult = await http.get(`${endpoint}?jobNumber=${jobNumber}`);
+
+  return {
+    status: finalResult.STATUS || finalResult.status,
+    result: finalResult.RESULT || finalResult.result,
+    startedAt: finalResult.STARTED_AT || finalResult.startedAt,
+    completedAt: finalResult.COMPLETED_AT || finalResult.completedAt,
+    jobNumber: finalResult.JOB_NUMBER || finalResult.jobNumber,
+    jobName: finalResult.JOB_NAME || finalResult.jobName
+  };
+}
+
+/**
+ * Display progress bar in console
+ *
+ * @param {number} progress - Progress percentage (0-100)
+ * @param {string} message - Progress message
+ * @param {Object} options - Display options
+ * @param {number} options.barWidth - Width of progress bar (default: 30)
+ * @param {boolean} options.showPercentage - Show percentage number (default: false)
+ */
+function displayProgress(progress, message, options = {}) {
+  const {
+    barWidth = 30,
+    showPercentage = false
+  } = options;
+
+  const filled = Math.floor(progress * barWidth / 100);
+  const empty = barWidth - filled;
+  const bar = '[' + '='.repeat(filled) + ' '.repeat(empty) + ']';
+
+  // Clear line and print progress
+  let output = `\r${bar}`;
+  if (showPercentage) {
+    output += ` ${progress}%`;
+  }
+  output += ` ${message}`;
+
+  process.stdout.write(output);
+}
+
+/**
+ * Format ABAP timestamp (YYYYMMDDHHMMSS) to readable local format
+ *
+ * @param {string|number} timestamp - ABAP timestamp
+ * @returns {string} Formatted timestamp (YYYY-MM-DD HH:MM:SS)
+ */
+function formatTimestamp(timestamp) {
+  if (!timestamp) return timestamp;
+
+  const ts = timestamp.toString();
+  if (ts.length !== 14) return timestamp;
+
+  const year = parseInt(ts.substr(0, 4));
+  const month = parseInt(ts.substr(4, 2)) - 1; // JS months are 0-indexed
+  const day = parseInt(ts.substr(6, 2));
+  const hour = parseInt(ts.substr(8, 2));
+  const minute = parseInt(ts.substr(10, 2));
+  const second = parseInt(ts.substr(12, 2));
+
+  // Create UTC date
+  const utcDate = new Date(Date.UTC(year, month, day, hour, minute, second));
+
+  // Format in local timezone
+  const localYear = utcDate.getFullYear();
+  const localMonth = String(utcDate.getMonth() + 1).padStart(2, '0');
+  const localDay = String(utcDate.getDate()).padStart(2, '0');
+  const localHour = String(utcDate.getHours()).padStart(2, '0');
+  const localMinute = String(utcDate.getMinutes()).padStart(2, '0');
+  const localSecond = String(utcDate.getSeconds()).padStart(2, '0');
+
+  return `${localYear}-${localMonth}-${localDay} ${localHour}:${localMinute}:${localSecond}`;
+}
+
+/**
+ * Calculate time difference between two ABAP timestamps
+ *
+ * @param {string|number} startTimestamp - Start timestamp (YYYYMMDDHHMMSS)
+ * @param {string|number} endTimestamp - End timestamp (YYYYMMDDHHMMSS)
+ * @returns {string} Human-readable duration (e.g., "2 minutes 30 seconds")
+ */
+function calculateTimeSpent(startTimestamp, endTimestamp) {
+  if (!startTimestamp || !endTimestamp) return 'unknown';
+
+  const start = parseAbapTimestamp(startTimestamp);
+  const end = parseAbapTimestamp(endTimestamp);
+
+  if (!start || !end) return 'unknown';
+
+  const diffMs = end - start;
+  const diffSeconds = Math.floor(diffMs / 1000);
+
+  if (diffSeconds < 60) {
+    return `${diffSeconds} second${diffSeconds !== 1 ? 's' : ''}`;
+  }
+
+  const minutes = Math.floor(diffSeconds / 60);
+  const seconds = diffSeconds % 60;
+
+  if (minutes < 60) {
+    if (seconds === 0) {
+      return `${minutes} minute${minutes !== 1 ? 's' : ''}`;
+    }
+    return `${minutes} minute${minutes !== 1 ? 's' : ''} ${seconds} second${seconds !== 1 ? 's' : ''}`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+
+  return `${hours} hour${hours !== 1 ? 's' : ''} ${remainingMinutes} minute${remainingMinutes !== 1 ? 's' : ''}`;
+}
+
+/**
+ * Parse ABAP timestamp to JavaScript Date
+ *
+ * @param {string|number} timestamp - ABAP timestamp (YYYYMMDDHHMMSS)
+ * @returns {Date|null} JavaScript Date object or null if invalid
+ */
+function parseAbapTimestamp(timestamp) {
+  if (!timestamp) return null;
+
+  const ts = timestamp.toString();
+  if (ts.length !== 14) return null;
+
+  const year = parseInt(ts.substr(0, 4));
+  const month = parseInt(ts.substr(4, 2)) - 1;
+  const day = parseInt(ts.substr(6, 2));
+  const hour = parseInt(ts.substr(8, 2));
+  const minute = parseInt(ts.substr(10, 2));
+  const second = parseInt(ts.substr(12, 2));
+
+  return new Date(Date.UTC(year, month, day, hour, minute, second));
+}
+
+/**
+ * Sleep for specified milliseconds
+ *
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise} Promise that resolves after ms milliseconds
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  startBackgroundJob,
+  pollForCompletion,
+  displayProgress,
+  formatTimestamp,
+  calculateTimeSpent,
+  parseAbapTimestamp,
+  sleep
+};