abapgit-agent 1.8.1 → 1.8.3

package/abap/CLAUDE.md

@@ -73,30 +73,38 @@ The folder is configured in `.abapGitAgent` (property: `folder`):
 
 **Each ABAP object requires an XML metadata file for abapGit to understand how to handle it.**
 
-| Object Type | ABAP File (if folder=/src/) | XML File |
-|-------------|------------------------------|----------|
-| Class | `src/zcl_*.clas.abap` | `src/zcl_*.clas.xml` |
-| Interface | `src/zif_*.intf.abap` | `src/zif_*.intf.xml` |
-| Program | `src/z*.prog.abap` | `src/z*.prog.xml` |
-| Table | `src/z*.tabl.abap` | `src/z*.tabl.xml` |
-| CDS View | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` |
+| Object Type | ABAP File (if folder=/src/) | XML File | Details |
+|-------------|------------------------------|----------|---------|
+| Class | `src/zcl_*.clas.abap` | `src/zcl_*.clas.xml` | See `guidelines/08_abapgit.md` |
+| Interface | `src/zif_*.intf.abap` | `src/zif_*.intf.xml` | See `guidelines/08_abapgit.md` |
+| Program | `src/z*.prog.abap` | `src/z*.prog.xml` | See `guidelines/08_abapgit.md` |
+| Table | `src/z*.tabl.abap` | `src/z*.tabl.xml` | See `guidelines/08_abapgit.md` |
+| **CDS View Entity** | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` | **Use by default** - See `guidelines/04_cds.md` |
+| CDS View (legacy) | `src/zc_*.ddls.asddls` | `src/zc_*.ddls.xml` | Only if explicitly requested - See `guidelines/04_cds.md` |
 
-**Use `ref --topic abapgit` for complete XML templates.**
+**IMPORTANT: When user says "create CDS view", create CDS View Entity by default.**
+
+**Why:** Modern S/4HANA standard, simpler (no SQL view), no namespace conflicts.
+
+**For complete XML templates, DDL examples, and detailed comparison:**
+- **CDS Views**: `guidelines/04_cds.md`
+- **XML templates**: `guidelines/08_abapgit.md`
 
 ---
 
-### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG)
+### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG, DDLS)
 
 ```
 ❌ WRONG: Make changes → Commit → Push → Pull → Find errors → Fix → Repeat
 ✅ CORRECT: Make changes → Run syntax → Fix locally → Commit → Push → Pull → Done
 ```
 
-**For CLAS, INTF, PROG files**: Run `syntax` command BEFORE commit to catch errors early.
+**For CLAS, INTF, PROG, DDLS files**: Run `syntax` command BEFORE commit to catch errors early.
 
 ```bash
 # Check syntax of local code (no commit/push needed)
 abapgit-agent syntax --files src/zcl_my_class.clas.abap
+abapgit-agent syntax --files src/zc_my_view.ddls.asddls
 
 # Check multiple INDEPENDENT files
 abapgit-agent syntax --files src/zcl_utils.clas.abap,src/zcl_logger.clas.abap
@@ -250,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
 ```
-1. Read .abapGitAgent → get folder value
+
+#### 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 AND workflow.mode
        │
        ▼
 2. Research → use ref command for unfamiliar topics
@@ -260,15 +449,15 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 3. Write code → place in correct folder (e.g., src/zcl_*.clas.abap)
        │
        ▼
-4. Syntax check (for CLAS, INTF, PROG only)
+4. Syntax check (for CLAS, INTF, PROG, DDLS only)
        │
-       ├─► CLAS/INTF/PROG → abapgit-agent syntax --files <file>
+       ├─► CLAS/INTF/PROG/DDLS → abapgit-agent syntax --files <file>
        │       │
        │       ├─► Errors? → Fix locally (no commit needed), re-run syntax
        │       │
        │       └─► Clean ✅ → Proceed to commit
        │
-       └─► Other types (DDLS, FUGR, TABL, etc.) → Skip syntax, go to commit
+       └─► Other types (FUGR, TABL, etc.) → Skip syntax, go to commit
                │
                ▼
 5. Commit and push → git add . && git commit && git push
@@ -301,34 +490,88 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 
 **IMPORTANT**:
 - **Use `syntax` BEFORE commit** for CLAS/INTF/PROG/DDLS - catches errors early, no git pollution
-- **Syntax checks files INDEPENDENTLY** - no cross-file dependency support (e.g., interface definition not available when checking implementing class)
-- **For dependent files** (interface + class, class + using class): Skip `syntax`, use `pull` directly
+- **Syntax checks files INDEPENDENTLY** - syntax checker doesn't have access to uncommitted files
+- **For dependent files** (interface + class): Create/activate underlying object FIRST, then dependent object (see workflow below)
 - **DDLS requires proper annotations** - CDS views need `@AbapCatalog.sqlViewName`, view entities don't
 - **ALWAYS push to git BEFORE running pull** - abapGit reads from git
 - **Use `inspect` AFTER pull** for unsupported types or if pull fails
 
+**Working with dependent objects (RECOMMENDED APPROACH):**
+
+When creating objects with dependencies (e.g., interface → class), create and activate the underlying object FIRST:
+
+```bash
+# Step 1: Create interface, syntax check, commit, activate
+vim src/zif_my_interface.intf.abap
+abapgit-agent syntax --files src/zif_my_interface.intf.abap  # ✅ Works (no dependencies)
+git add src/zif_my_interface.intf.abap src/zif_my_interface.intf.xml
+git commit -m "feat: add interface"
+git push
+abapgit-agent pull --files src/zif_my_interface.intf.abap   # Interface now activated
+
+# Step 2: Create class, syntax check, commit, activate
+vim src/zcl_my_class.clas.abap
+abapgit-agent syntax --files src/zcl_my_class.clas.abap     # ✅ Works (interface already activated)
+git add src/zcl_my_class.clas.abap src/zcl_my_class.clas.xml
+git commit -m "feat: add class implementing interface"
+git push
+abapgit-agent pull --files src/zcl_my_class.clas.abap
+```
+
+**Benefits:**
+- ✅ Syntax checking works for both objects
+- ✅ Each step is validated independently
+- ✅ Easier to debug if something fails
+- ✅ Cleaner workflow
+
+**Alternative approach (when interface design is uncertain):**
+
+If the interface might need changes while implementing the class, commit both together:
+
+```bash
+# Create both files
+vim src/zif_my_interface.intf.abap
+vim src/zcl_my_class.clas.abap
+
+# Skip syntax (files depend on each other), commit together
+git add src/zif_my_interface.intf.abap src/zif_my_interface.intf.xml
+git add src/zcl_my_class.clas.abap src/zcl_my_class.clas.xml
+git commit -m "feat: add interface and implementing class"
+git push
+
+# Pull both together
+abapgit-agent pull --files src/zif_my_interface.intf.abap,src/zcl_my_class.clas.abap
+
+# Use inspect if errors occur
+abapgit-agent inspect --files src/zcl_my_class.clas.abap
+```
+
+**Use this approach when:**
+- ❌ Interface design is still evolving
+- ❌ Multiple iterations expected
+
 **Working with mixed file types:**
 When modifying multiple files of different types (e.g., 1 class + 1 CDS view):
-1. Run `syntax` on supported files only (CLAS, INTF, PROG) - **only if they're independent**
+1. Run `syntax` on independent supported files (CLAS, INTF, PROG, DDLS)
 2. Commit ALL files together (including unsupported types)
 3. Push and pull ALL files together
 
 Example:
 ```bash
-# Check syntax on independent class and interface only (skip CDS, skip if dependent)
-abapgit-agent syntax --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap
+# Check syntax on independent files only
+abapgit-agent syntax --files src/zcl_my_class.clas.abap,src/zc_my_view.ddls.asddls
 
-# Commit and push all files including CDS
-git add src/zcl_my_class.clas.abap src/zif_my_intf.intf.abap src/zc_my_view.ddls.asddls
-git commit -m "feat: add class, interface, and CDS view"
+# Commit and push all files
+git add src/zcl_my_class.clas.abap src/zc_my_view.ddls.asddls
+git commit -m "feat: add class and CDS view"
 git push
 
 # Pull all files together
-abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap,src/zc_my_view.ddls.asddls
+abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zc_my_view.ddls.asddls
 ```
 
 **When to use syntax vs inspect vs view**:
-- **syntax**: Check LOCAL code BEFORE commit (CLAS, INTF, PROG only)
+- **syntax**: Check LOCAL code BEFORE commit (CLAS, INTF, PROG, DDLS)
 - **inspect**: Check ACTIVATED code AFTER pull (all types, runs Code Inspector)
 - **view**: Understand object STRUCTURE (not for debugging errors)
 
@@ -338,21 +581,29 @@ abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap,
 
 ```
 1. Identify file extension(s) AND dependencies
-   ├─ .clas.abap or .clas.testclasses.abap → CLAS ✅ syntax supported (if independent)
-   ├─ .intf.abap → INTF ✅ syntax supported (if independent)
+   ├─ .clas.abap or .clas.testclasses.abap → CLAS ✅ syntax supported
+   ├─ .intf.abap → INTF ✅ syntax supported
    ├─ .prog.abap → PROG ✅ syntax supported
    ├─ .ddls.asddls → DDLS ✅ syntax supported (requires proper annotations)
    └─ All other extensions → ❌ syntax not supported
 
 2. Check for dependencies:
-   ├─ Interface + implementing class? → Dependencies exist
-   ├─ Class A uses class B? → Dependencies exist
-   ├─ New objects that don't exist in ABAP system? → Check if they depend on each other
-   └─ Unrelated bug fixes across files? → No dependencies
+   ├─ Interface + implementing class? → DEPENDENT (interface is underlying)
+   ├─ Class A uses class B? → DEPENDENT (class B is underlying)
+   ├─ CDS view uses table? → INDEPENDENT (table already exists)
+   └─ Unrelated bug fixes across files? → INDEPENDENT
 
 3. For SUPPORTED types (CLAS/INTF/PROG/DDLS):
-   ├─ Independent files → Run syntax → Fix errors → Commit → Push → Pull
-   └─ Dependent files → Skip syntax → Commit → Push → Pull
+   ├─ INDEPENDENT files → Run syntax → Fix errors → Commit → Push → Pull
+   │
+   └─ DEPENDENT files (NEW objects):
+       ├─ RECOMMENDED: Create underlying object first (interface, base class, etc.)
+       │   1. Create underlying object → Syntax → Commit → Push → Pull
+       │   2. Create dependent object → Syntax (works!) → Commit → Push → Pull
+       │   ✅ Benefits: Both syntax checks work, cleaner workflow
+       │
+       └─ ALTERNATIVE: If interface design uncertain, commit both together
+           → Skip syntax → Commit both → Push → Pull → (if errors: inspect)
 
 4. For UNSUPPORTED types (FUGR, TABL, etc.):
    Write code → Skip syntax → Commit → Push → Pull → (if errors: inspect)
@@ -361,6 +612,32 @@ abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap,
    Write all code → Run syntax on independent supported files ONLY → Commit ALL → Push → Pull ALL
 ```
 
+**Example workflows:**
+
+**Scenario 1: Interface + Class (RECOMMENDED)**
+```bash
+# Step 1: Interface first
+vim src/zif_calculator.intf.abap
+abapgit-agent syntax --files src/zif_calculator.intf.abap  # ✅ Works
+git commit -am "feat: add calculator interface" && git push
+abapgit-agent pull --files src/zif_calculator.intf.abap    # Interface activated
+
+# Step 2: Class next
+vim src/zcl_calculator.clas.abap
+abapgit-agent syntax --files src/zcl_calculator.clas.abap  # ✅ Works (interface exists!)
+git commit -am "feat: implement calculator" && git push
+abapgit-agent pull --files src/zcl_calculator.clas.abap
+```
+
+**Scenario 2: Multiple independent classes**
+```bash
+# All syntax checks work (no dependencies)
+vim src/zcl_class1.clas.abap src/zcl_class2.clas.abap
+abapgit-agent syntax --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap
+git commit -am "feat: add utility classes" && git push
+abapgit-agent pull --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap
+```
+
 **Error indicators after pull:**
 - ❌ **"Error updating where-used list"** → SYNTAX ERROR - run `inspect` for details
 - ❌ **Objects in "Failed Objects Log"** → SYNTAX ERROR - run `inspect`
@@ -370,9 +647,10 @@ abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap,
 ### Commands
 
 ```bash
-# 1. Syntax check LOCAL code BEFORE commit (CLAS, INTF, PROG only)
+# 1. Syntax check LOCAL code BEFORE commit (CLAS, INTF, PROG, DDLS)
 abapgit-agent syntax --files src/zcl_my_class.clas.abap
-abapgit-agent syntax --files src/zcl_class1.clas.abap,src/zif_intf1.intf.abap
+abapgit-agent syntax --files src/zc_my_view.ddls.asddls
+abapgit-agent syntax --files src/zcl_class1.clas.abap,src/zif_intf1.intf.abap,src/zc_view.ddls.asddls
 
 # 2. Pull/activate AFTER pushing to git
 abapgit-agent pull --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap

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.1",
+  "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
 };