abapgit-agent 1.8.2 → 1.8.3

package/abap/CLAUDE.md

@@ -258,8 +258,189 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 
 ## Development Workflow
 
+This project's workflow mode is configured in `.abapGitAgent` under `workflow.mode`.
+
+### Workflow Modes
+
+| Mode | Branch Strategy | Rebase Before Pull | Create PR |
+|------|----------------|-------------------|-----------|
+| `"branch"` | Feature branches | ✓ Always | ✓ Yes (squash merge) |
+| `"trunk"` | Direct to default branch | ✗ No | ✗ No |
+| (not set) | Direct to default branch | ✗ No | ✗ No |
+
+**Default branch** (main/master/develop) is **auto-detected** from your git repository.
+
+### Branch Workflow (`"mode": "branch"`)
+
+**IMPORTANT**: Always work on feature branches, never commit directly to the default branch.
+
+#### Starting a New Feature
+
+```bash
+# 1. Create and switch to feature branch from default branch
+git checkout main  # or master/develop (auto-detected)
+git pull origin main
+git checkout -b feature/user-authentication
+
+# 2. Make your changes
+edit src/zcl_auth_handler.clas.abap
+
+# 3. Check syntax (CLAS/INTF/PROG/DDLS only, if independent)
+abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
+
+# 4. Commit
+git add src/zcl_auth_handler.clas.abap
+git commit -m "feat: add authentication handler"
+
+# 5. Push feature branch
+git push origin feature/user-authentication
+
+# 6. **CRITICAL**: Rebase before pull
+git fetch origin main
+git rebase origin/main
+git push origin feature/user-authentication --force-with-lease
+
+# 7. Pull to ABAP system
+abapgit-agent pull --files src/zcl_auth_handler.clas.abap
+```
+
+#### During Development: Always Rebase Before Pull
+
+**CRITICAL**: Before every `pull` command, rebase to default branch to avoid activating outdated code.
+
+```bash
+# Before EVERY pull, always do this:
+git fetch origin main  # main/master/develop (auto-detected)
+git rebase origin/main
+
+# If no conflicts:
+git push origin feature/user-authentication --force-with-lease
+abapgit-agent pull --files src/zcl_auth_handler.clas.abap
+
+# If conflicts:
+# 1. Fix conflicts in files
+# 2. git add <resolved-files>
+# 3. git rebase --continue
+# 4. git push origin feature/user-authentication --force-with-lease
+# 5. abapgit-agent pull --files ...
+```
+
+#### Completing the Feature
+
+```bash
+# 1. Final rebase and push
+git fetch origin main
+git rebase origin/main
+git push origin feature/user-authentication --force-with-lease
+
+# 2. Final activation and test
+abapgit-agent pull --files src/zcl_auth_handler.clas.abap
+abapgit-agent unit --files src/zcl_auth_handler.clas.testclasses.abap
+
+# 3. Create PR (squash merge enabled on GitHub/GitLab)
+# Go to GitHub and create PR from feature/user-authentication to main
+# Select "Squash and merge" option to combine all commits into one
+```
+
+#### Why Rebase Before Pull?
+
+ABAP is a **centralized system**. Multiple developers may modify the same files:
+
+| Without Rebase | With Rebase |
+|----------------|-------------|
+| ✗ Your branch is based on old main | ✓ Your branch includes latest changes |
+| ✗ Activate outdated code in ABAP | ✓ Activate current code |
+| ✗ May overwrite others' work | ✓ Conflicts caught before activation |
+| ✗ Hard to debug issues | ✓ Clear what changed |
+
+**Example Scenario:**
+
+```
+Situation:
+- You: working on feature/auth (based on main commit A)
+- Colleague: pushed to main (now at commit B)
+- Both modified: src/zcl_auth_handler.clas.abap
+
+Without rebase:
+  feature/auth pull → activates version from commit A ✗
+
+With rebase:
+  git rebase origin/main → either:
+    - No conflict: includes colleague's changes ✓
+    - Conflict: you see it and resolve ✓
+```
+
+#### Complete Example Workflow (Branch Mode)
+
+```bash
+# Day 1: Start feature
+git checkout main && git pull origin main
+git checkout -b feature/user-authentication
+edit src/zcl_auth_handler.clas.abap
+abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
+git add . && git commit -m "wip: add basic auth logic"
+git push origin feature/user-authentication
+git fetch origin main && git rebase origin/main
+git push origin feature/user-authentication --force-with-lease
+abapgit-agent pull --files src/zcl_auth_handler.clas.abap
+
+# Day 2: Continue (colleague pushed to main overnight)
+git fetch origin main && git rebase origin/main
+# If conflicts: resolve, git add, git rebase --continue
+git push origin feature/user-authentication --force-with-lease
+edit src/zcl_auth_handler.clas.abap
+git add . && git commit -m "feat: complete auth logic"
+git push origin feature/user-authentication
+git fetch origin main && git rebase origin/main
+git push origin feature/user-authentication --force-with-lease
+abapgit-agent pull --files src/zcl_auth_handler.clas.abap
+
+# Day 3: Finish feature
+abapgit-agent unit --files src/zcl_auth_handler.clas.testclasses.abap
+git fetch origin main && git rebase origin/main
+git push origin feature/user-authentication --force-with-lease
+# Create PR on GitHub/GitLab (squash 3 commits into 1)
+```
+
+### Trunk Workflow (`"mode": "trunk"`)
+
+If workflow mode is `"trunk"` or not set, commit directly to the default branch:
+
+```bash
+git checkout main  # or master/develop (auto-detected)
+git pull origin main
+edit src/zcl_auth_handler.clas.abap
+abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
+git add . && git commit -m "feat: add authentication handler"
+git push origin main
+abapgit-agent pull --files src/zcl_auth_handler.clas.abap
+```
+
+### AI Tool Guidelines
+
+**Read `.abapGitAgent` to determine workflow mode:**
+
+**When `workflow.mode = "branch"`:**
+1. ✓ Auto-detect default branch (main/master/develop)
+2. ✓ Create feature branches (naming: `feature/description`)
+3. ✓ Always `git fetch origin <default> && git rebase origin/<default>` before `pull` command
+4. ✓ Use `--force-with-lease` after rebase (never `--force`)
+5. ✓ Create PR with squash merge when feature complete
+6. ✗ Never commit directly to default branch
+7. ✗ Never use `git push --force` (always use `--force-with-lease`)
+
+**When `workflow.mode = "trunk"` or not set:**
+1. ✓ Commit directly to default branch
+2. ✓ Keep commits clean and atomic
+3. ✓ `git pull origin <default>` before push
+4. ✗ Don't create feature branches
+
+---
+
+## Development Workflow (Detailed)
+
 ```
-1. Read .abapGitAgent → get folder value
+1. Read .abapGitAgent → get folder value AND workflow.mode
        │
        ▼
 2. Research → use ref command for unfamiliar topics

package/abap/guidelines/03_testing.md

@@ -11,12 +11,13 @@ grand_parent: ABAP Development
 **Searchable keywords**: unit test, AUnit, test class, cl_abap_unit_assert, FOR TESTING, setup, teardown, RISK LEVEL, DURATION, CDS test double, CL_CDS_TEST_ENVIRONMENT
 
 ## TOPICS IN THIS FILE
-1. Local Test Classes - line 3
-2. File Structure - line 5
-3. Required Elements - line 16
-4. Naming Conventions - line 48
-5. CDS Test Doubles - line 94
-6. CDS with Aggregations - line 178
+1. Local Test Classes - line 22
+2. File Structure - line 24
+3. Required Elements - line 35
+4. Naming Conventions - line 67
+5. Common Mistake: DDLS Testing - line 133
+6. CDS Test Doubles - line 163
+7. CDS with Aggregations - line 247
 
 ## Unit Testing with Local Test Classes
 
@@ -122,6 +123,44 @@ cl_abap_unit_assert=>assert_true( act = lv_bool msg = 'Should be true' ).
 - ❌ Don't reference `<TESTCLASS>` in XML - abapGit auto-detects `.testclasses.abap`
 - ❌ Don't use nested local classes inside the main class definition
 
+---
+
+### ⚠️ Common Mistake: CDS Views Don't Have `.testclasses.abap` Files
+
+**WRONG - Creating test file for DDLS**:
+```
+zc_my_view.ddls.asddls
+zc_my_view.ddls.testclasses.abap  ❌ This doesn't work!
+zc_my_view.ddls.xml
+```
+
+**Error you'll see**:
+```
+The REPORT/PROGRAM statement is missing, or the program type is INCLUDE.
+```
+
+**CORRECT - Test CDS views using separate CLAS test classes**:
+```
+zc_flight_revenue.ddls.asddls               ← CDS view definition
+zc_flight_revenue.ddls.xml                  ← CDS metadata
+
+zcl_test_flight_revenue.clas.abap           ← Test class definition
+zcl_test_flight_revenue.clas.testclasses.abap  ← Test implementation
+zcl_test_flight_revenue.clas.xml            ← Class metadata (WITH_UNIT_TESTS=X)
+```
+
+**Why**: Each ABAP object type has its own testing pattern:
+- **CLAS** (classes): Use `.clas.testclasses.abap` for the same class
+- **DDLS** (CDS views): Use separate CLAS test class with CDS Test Double Framework
+- **FUGR** (function groups): Use `.fugr.testclasses.abap`
+- **PROG** (programs): Use `.prog.testclasses.abap`
+
+**Don't assume patterns from one object type apply to another!**
+
+See "Unit Testing CDS Views" section below for the correct CDS testing approach.
+
+---
+
 ### Running Tests
 
 In ABAP: SE24 → Test → Execute Unit Tests

package/abap/guidelines/04_cds.md

@@ -11,11 +11,15 @@ grand_parent: ABAP Development
 **Searchable keywords**: CDS, DDL, DDLS, CDS view, @AbapCatalog, @AccessControl, association, projection, consumption
 
 ## TOPICS IN THIS FILE
-1. File Naming - line 7
-2. DDL Source (.ddls.asddls) - line 18
-3. Annotations - line 50
-4. Associations - line 75
-5. CDS Test Doubles - see 03_testing.md
+1. File Naming - line 96
+2. DDL Source (.ddls.asddls) - line 107
+3. Annotations - line 141
+4. Associations - line 164
+5. CDS Best Practices - line 194
+   - Key Field Ordering (STRICT RULE) - line 198
+   - Currency/Amount Field Aggregation - line 230
+   - Choosing Currency Fields for Aggregation - line 255
+6. CDS Test Doubles - see 03_testing.md
 
 ## Creating CDS Views (DDLS)
 
@@ -188,6 +192,110 @@ where devclass not like '$%'
 3. **Expose associations**: Add the association name at the end of the SELECT to expose it for OData navigation
 4. **Activation warnings**: Search help warnings are informational and don't block activation
 
+---
+
+## CDS Best Practices and Common Patterns
+
+### Key Field Ordering (STRICT RULE)
+
+CDS views enforce strict key field ordering that differs from regular SQL:
+
+❌ **WRONG - Non-key field between keys**:
+```abap
+{
+  key Flight.carrid as Carrid,
+      Airline.carrname as Carrname,  // ← breaks contiguity!
+  key Flight.connid as Connid,
+  key Flight.fldate as Fldate,
+  ...
+}
+```
+
+✅ **CORRECT - All keys first, then non-keys**:
+```abap
+{
+  key Flight.carrid as Carrid,
+  key Flight.connid as Connid,
+  key Flight.fldate as Fldate,
+      Airline.carrname as Carrname,  // ← after all keys
+  ...
+}
+```
+
+**Rules:**
+1. All key fields MUST be at the beginning of the field list
+2. Key fields MUST be contiguous (no non-key fields in between)
+3. Key fields must be declared before any non-key fields
+
+**Error message**: "Key must be contiguous and start at the first position"
+
+**Why this rule exists**: CDS views are not just SQL - they represent data models with strict structural requirements for consistency across the system.
+
+---
+
+### Currency/Amount Field Aggregation
+
+When aggregating currency or amount fields in CDS views, use semantic annotations instead of complex casting:
+
+❌ **WRONG - Complex casting (will fail)**:
+```abap
+cast(coalesce(sum(Booking.loccuram), 0) as abap.curr(15,2))
+// Error: Data type CURR is not supported at this position
+```
+
+✅ **CORRECT - Semantic annotation + simple aggregation**:
+```abap
+@Semantics.amount.currencyCode: 'Currency'
+sum(Booking.loccuram) as TotalRevenue,
+currency             as Currency
+```
+
+**Key points:**
+- Use `@Semantics.amount.currencyCode` to link amount to currency field
+- Let the framework handle data typing automatically
+- Don't over-engineer with casts or type conversions
+- Keep it simple: annotation + aggregation function
+
+**Reference**:
+```bash
+abapgit-agent ref "CDS aggregation"
+# Check: zdemo_abap_cds_ve_agg_exp.ddls.asddls for working examples
+```
+
+---
+
+### Choosing Currency Fields for Aggregation
+
+**Understand your data model before aggregating currency fields** - not all currency fields can be safely summed:
+
+❌ **Dangerous - Foreign currency (different keys per row)**:
+```abap
+sum(Booking.forcuram)  // FORCURAM has different FORCURKEY per booking!
+// Problem: Can't safely sum USD + EUR + GBP without conversion
+```
+
+✅ **Safe - Local currency (shared key per group)**:
+```abap
+sum(Booking.loccuram)  // LOCCURAM shares LOCCURKEY per airline
+// Safe: All bookings for one airline use the same currency
+```
+
+**Data Model Example (SBOOK table)**:
+```
+FORCURAM + FORCURKEY = Payment currency (USD, EUR, GBP - different per booking)
+LOCCURAM + LOCCURKEY = Airline currency (one currency per airline)
+```
+
+**Analysis Steps:**
+1. Identify all currency fields in source tables
+2. Check which currency code field each amount uses
+3. Verify currency code is constant within your aggregation groups
+4. Choose the field with consistent currency per group
+
+**Rule**: Only aggregate amounts that share the same currency code within your grouping (GROUP BY).
+
+---
+
 ## CDS Syntax Reference
 
 When working with CDS view syntax (arithmetic, built-in functions, aggregations, etc.):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [
@@ -34,6 +34,7 @@
     "test:cmd:preview": "node tests/run-all.js --cmd --command=preview",
     "test:cmd:tree": "node tests/run-all.js --cmd --command=tree",
     "test:lifecycle": "node tests/run-all.js --lifecycle",
+    "test:pull": "node tests/run-all.js --pull",
     "pull": "node bin/abapgit-agent",
     "release": "node scripts/release.js",
     "unrelease": "node scripts/unrelease.js"

package/src/commands/init.js

@@ -172,39 +172,100 @@ module.exports = {
     }
     console.log(`📌 Git remote: ${gitUrl}`);
 
-    // Check if .abapGitAgent already exists
+    // Check if .abapGitAgent already exists - merge if it does
     const configPath = pathModule.join(process.cwd(), '.abapGitAgent');
+    let config = null;
+    let isUpdate = false;
+
     if (fs.existsSync(configPath)) {
-      console.error('Error: .abapGitAgent already exists.');
-      console.error('To reinitialize, delete the existing file first.');
-      process.exit(1);
-    }
+      isUpdate = true;
+      try {
+        // Read existing configuration
+        const currentConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+
+        console.log('📝 Updating existing .abapGitAgent configuration');
+        console.log('');
+        console.log('Current values:');
+        console.log(`   Package: ${currentConfig.package || '(not set)'}`);
+        console.log(`   Folder:  ${currentConfig.folder || '(not set)'}`);
+        console.log(`   Host:    ${currentConfig.host || '(not set)'}`);
+        console.log('');
+
+        // Merge: keep existing values, update package and folder
+        config = currentConfig;
+
+        // Track what changed
+        const changes = [];
+
+        if (packageName && packageName !== currentConfig.package) {
+          const oldValue = currentConfig.package || '(not set)';
+          config.package = packageName;
+          changes.push(`package: ${oldValue} → ${packageName}`);
+        }
 
-    // Copy .abapGitAgent.example to .abapGitAgent
-    const samplePath = pathModule.join(__dirname, '..', '..', '.abapGitAgent.example');
-    if (!fs.existsSync(samplePath)) {
-      console.error('Error: .abapGitAgent.example not found.');
-      process.exit(1);
+        if (folder && folder !== currentConfig.folder) {
+          const oldValue = currentConfig.folder || '(not set)';
+          config.folder = folder;
+          changes.push(`folder: ${oldValue} → ${folder}`);
+        }
+
+        if (changes.length === 0) {
+          console.log('⚠️  No changes needed - package and folder are already set correctly');
+          console.log('');
+          console.log('To change other settings, edit .abapGitAgent manually');
+          // Don't exit - continue with other setup tasks (CLAUDE.md, guidelines, etc.)
+        } else {
+          console.log('Changes to be made:');
+          changes.forEach(change => console.log(`   ${change}`));
+          console.log('');
+          console.log('✅ Keeping all other settings (host, credentials, workflow, etc.)');
+          console.log('');
+        }
+      } catch (error) {
+        console.error('Error: .abapGitAgent exists but could not read it:');
+        console.error(`   ${error.message}`);
+        console.error('');
+        console.error('To fix:');
+        console.error('   1. Check if .abapGitAgent contains valid JSON');
+        console.error('   2. Or delete it: rm .abapGitAgent');
+        process.exit(1);
+      }
+    } else {
+      // Create new config from template
+      const samplePath = pathModule.join(__dirname, '..', '..', '.abapGitAgent.example');
+      if (!fs.existsSync(samplePath)) {
+        console.error('Error: .abapGitAgent.example not found.');
+        process.exit(1);
+      }
+
+      try {
+        // Read sample and update with package/folder
+        const sampleContent = fs.readFileSync(samplePath, 'utf8');
+        config = JSON.parse(sampleContent);
+        config.package = packageName;
+        config.folder = folder;
+      } catch (error) {
+        console.error(`Error reading .abapGitAgent.example: ${error.message}`);
+        process.exit(1);
+      }
     }
 
+    // Write the config (either new or updated)
     try {
-      // Read sample and update with package/folder
-      const sampleContent = fs.readFileSync(samplePath, 'utf8');
-      const config = JSON.parse(sampleContent);
-      config.package = packageName;
-      config.folder = folder;
-
-      // Write updated config
       fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
-      console.log(`✅ Created .abapGitAgent`);
+      if (isUpdate) {
+        console.log(`✅ Updated .abapGitAgent`);
+      } else {
+        console.log(`✅ Created .abapGitAgent`);
+      }
     } catch (error) {
-      console.error(`Error creating .abapGitAgent: ${error.message}`);
+      console.error(`Error writing .abapGitAgent: ${error.message}`);
       process.exit(1);
     }
 
     // Update .gitignore
     const gitignorePath = pathModule.join(process.cwd(), '.gitignore');
-    const ignoreEntries = ['.abapGitAgent', '.abapgit_agent_cookies.txt'];
+    const ignoreEntries = ['.abapGitAgent'];
     let existingIgnore = '';
 
     if (fs.existsSync(gitignorePath)) {

package/src/commands/ref.js

@@ -63,7 +63,7 @@ module.exports = {
     }
 
     // Pattern search (default)
-    const patternIndex = args.findIndex((arg, idx) => idx > 0 && !arg.startsWith('--'));
+    const patternIndex = args.findIndex(arg => !arg.startsWith('--'));
     if (patternIndex === -1) {
       console.error('Error: No pattern specified');
       console.error('');

package/src/config.js

@@ -74,10 +74,25 @@ function isAbapIntegrationEnabled() {
   return fs.existsSync(repoConfigPath);
 }
 
+/**
+ * Get workflow configuration
+ * @returns {Object} Workflow config with mode ('branch' or 'trunk') and optional defaultBranch
+ */
+function getWorkflowConfig() {
+  const cfg = loadConfig();
+
+  // Default to trunk mode if not specified (backward compatible)
+  return {
+    mode: cfg.workflow?.mode || 'trunk',
+    defaultBranch: cfg.workflow?.defaultBranch || null  // null means auto-detect
+  };
+}
+
 module.exports = {
   loadConfig,
   getAbapConfig,
   getAgentConfig,
   getTransport,
-  isAbapIntegrationEnabled
+  isAbapIntegrationEnabled,
+  getWorkflowConfig
 };

package/src/utils/git-utils.js

@@ -3,6 +3,7 @@
  */
 const pathModule = require('path');
 const fs = require('fs');
+const { execSync } = require('child_process');
 
 /**
  * Get git remote URL from .git/config
@@ -51,8 +52,55 @@ function isGitRepo() {
   return fs.existsSync(gitPath);
 }
 
+/**
+ * Get the default/trunk branch name (main, master, develop, etc.)
+ * @param {string|null} configuredBranch - Branch name from config (overrides auto-detection)
+ * @returns {string} Default branch name
+ */
+function getDefaultBranch(configuredBranch = null) {
+  // If explicitly configured, use that
+  if (configuredBranch) {
+    return configuredBranch;
+  }
+
+  // Method 1: Check remote HEAD (most accurate)
+  try {
+    const result = execSync('git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null', {
+      cwd: process.cwd(),
+      encoding: 'utf8'
+    }).trim();
+
+    // Result looks like: refs/remotes/origin/main
+    const match = result.match(/refs\/remotes\/origin\/(.+)/);
+    if (match && match[1]) {
+      return match[1];
+    }
+  } catch (e) {
+    // Ignore error, try next method
+  }
+
+  // Method 2: Check common branch names in remote
+  try {
+    const branches = execSync('git branch -r 2>/dev/null', {
+      cwd: process.cwd(),
+      encoding: 'utf8'
+    });
+
+    // Check in order of preference: main > master > develop
+    if (branches.includes('origin/main')) return 'main';
+    if (branches.includes('origin/master')) return 'master';
+    if (branches.includes('origin/develop')) return 'develop';
+  } catch (e) {
+    // Ignore error, use fallback
+  }
+
+  // Method 3: Fallback to 'main' (modern default)
+  return 'main';
+}
+
 module.exports = {
   getRemoteUrl,
   getBranch,
-  isGitRepo
+  isGitRepo,
+  getDefaultBranch
 };