abapgit-agent 1.7.1 → 1.7.2

package/.abapGitAgent.example

@@ -0,0 +1,11 @@
+{
+  "host": "your-sap-system.com",
+  "sapport": 443,
+  "client": "100",
+  "user": "TECH_USER",
+  "password": "your-password",
+  "language": "EN",
+  "gitUsername": "github-username",
+  "gitPassword": "github-token",
+  "referenceFolder": "~/abap-reference"
+}

package/abap/.github/copilot-instructions.md

@@ -0,0 +1,254 @@
+# ABAP Development with abapGit
+
+You are working on an ABAP project using abapGit for version control.
+
+---
+
+## Critical Rules
+
+### 1. Use `ref` Command for Unfamiliar Topics
+
+**When starting to work on ANY unfamiliar ABAP topic, syntax, or pattern, you MUST use the `ref` command BEFORE writing any code.**
+
+```
+❌ WRONG: Start writing code immediately based on assumptions
+✅ CORRECT: Run ref command first to look up the correct pattern
+```
+
+**Why**: ABAP syntax is strict. Guessing leads to activation errors that waste time.
+
+| Scenario | Example |
+|----------|---------|
+| Implementing new ABAP feature | "How do I use FILTER operator?" |
+| Unfamiliar pattern | "What's the correct VALUE #() syntax?" |
+| SQL operations | "How to write a proper SELECT with JOIN?" |
+| CDS views | "How to define CDS view with associations?" |
+| Getting syntax errors | Check reference before trying approaches |
+
+```bash
+# For CDS topics
+abapgit-agent ref --topic cds
+abapgit-agent ref "CDS view"
+abapgit-agent ref "association"
+```
+
+```bash
+# Search for a pattern
+abapgit-agent ref "CORRESPONDING"
+abapgit-agent ref "FILTER #"
+
+# Browse by topic
+abapgit-agent ref --topic exceptions
+abapgit-agent ref --topic sql
+
+# List all topics
+abapgit-agent ref --list-topics
+```
+
+### 2. Read `.abapGitAgent` for Folder Location
+
+**Before creating ANY ABAP object file, you MUST read `.abapGitAgent` to determine the correct folder.**
+
+```
+❌ WRONG: Assume files go in "abap/" folder
+✅ CORRECT: Read .abapGitAgent to get the "folder" property value
+```
+
+The folder is configured in `.abapGitAgent` (property: `folder`):
+- If `folder` is `/src/` → files go in `src/` (e.g., `src/zcl_my_class.clas.abap`)
+- If `folder` is `/abap/` → files go in `abap/` (e.g., `abap/zcl_my_class.clas.abap`)
+
+### 3. Create XML Metadata for Each ABAP Object
+
+**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` |
+
+**Use `ref --topic abapgit` for complete XML templates.**
+
+### 4. Use `unit` Command for Unit Tests
+
+**Use `abapgit-agent unit` to run ABAP unit tests (AUnit).**
+
+```
+❌ WRONG: Try to use SE24 or other transaction codes
+✅ CORRECT: Use abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
+```
+
+```bash
+# Run unit tests (after pulling to ABAP)
+abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
+```
+
+### 5. Use CDS Test Double Framework for CDS View Tests
+
+**When creating unit tests for CDS views, use the CDS Test Double Framework (`CL_CDS_TEST_ENVIRONMENT`).**
+
+```
+❌ WRONG: Use regular AUnit test class without test doubles
+✅ CORRECT: Use CL_CDS_TEST_ENVIRONMENT to create test doubles for CDS views
+```
+
+**Why**: CDS views read from database tables. Using test doubles allows:
+- Injecting test data without affecting production data
+- Testing specific scenarios that may not exist in production
+- Fast, isolated tests that don't depend on database state
+
+See `../guidelines/03_testing.md` for code examples.
+
+---
+
+## Development Workflow
+
+```
+1. Read .abapGitAgent → get folder value
+       │
+       ▼
+2. Research → use ref command for unfamiliar topics
+       │
+       ▼
+3. Write code → place in correct folder (e.g., src/zcl_*.clas.abap)
+       │
+       ▼
+4. Commit and push → git add . && git commit && git push
+       │
+       ▼
+5. Activate → abapgit-agent pull --files src/file.clas.abap
+       │
+       ▼
+6. Verify → Check pull output
+   - **Do NOT run inspect before commit/push/pull** - ABAP validates on pull
+   - **Do NOT run unit before pull** - Tests run against ABAP system, code must be activated first
+   - Objects NOT in "Activated Objects" but in "Failed Objects Log" → Syntax error (check inspect)
+   - Objects NOT appearing at all → XML metadata issue
+       │
+       ▼
+7. (Optional) Run unit tests → abapgit-agent unit --files src/zcl_test.clas.testclasses.abap (ONLY if test file exists, AFTER successful pull)
+       │
+       ▼
+8. If needed → Use inspect to check syntax (runs against ABAP system)
+```
+
+**IMPORTANT**:
+- **ALWAYS push to git BEFORE running pull** - abapGit reads from git
+- **Use inspect AFTER pull** to check syntax on objects already in ABAP
+- **Check pull output**:
+  - In "Failed Objects Log" → Syntax error (use inspect for details)
+  - Not appearing at all → XML metadata is wrong
+
+**When to use inspect vs view**:
+- **inspect**: Use when there are SYNTAX ERRORS (to find line numbers and details)
+- **view**: Use when you need to understand an object STRUCTURE (table fields, class methods)
+- Do NOT use view to debug syntax errors - view shows definitions, not errors
+
+### Commands
+
+```bash
+# 1. Pull/activate after pushing to git (abapGit reads from git!)
+abapgit-agent pull --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap
+
+# 2. Inspect AFTER pull to check syntax (runs against ABAP system)
+abapgit-agent inspect --files src/zcl_class1.clas.abap,src/zif_interface1.intf.abap
+
+# Run unit tests (multiple test classes)
+abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
+
+# View object definitions (multiple objects)
+abapgit-agent view --objects ZCL_CLASS1,ZCL_CLASS2,ZIF_INTERFACE
+
+# Preview table data (multiple tables/views)
+abapgit-agent preview --objects ZTABLE1,ZTABLE2
+
+# Explore table structures
+abapgit-agent view --objects ZTABLE --type TABL
+
+# Display package tree
+abapgit-agent tree --package \$MY_PACKAGE
+```
+
+---
+
+## Explore Unknown Objects
+
+**Before working with unfamiliar objects, use `view` command:**
+
+```bash
+# Check table structure
+abapgit-agent view --objects ZMY_TABLE --type TABL
+
+# Check class definition
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS
+
+# Check interface
+abapgit-agent view --objects ZIF_UNKNOWN_INTERFACE
+
+# Check data element
+abapgit-agent view --objects ZMY_DTEL --type DTEL
+```
+
+AI assistant SHOULD call `view` command when:
+- User asks to "check", "look up", or "explore" an unfamiliar object
+- Working with a table/structure and you don't know the fields
+- Calling a class/interface method and you don't know the parameters
+
+---
+
+## Key ABAP Rules
+
+1. **Global classes MUST use `PUBLIC`**:
+   ```abap
+   CLASS zcl_my_class DEFINITION PUBLIC.  " <- REQUIRED
+   ```
+
+2. **Use `/ui2/cl_json` for JSON**:
+   ```abap
+   DATA ls_data TYPE ty_request.
+   ls_data = /ui2/cl_json=>deserialize( json = lv_json ).
+   lv_json = /ui2/cl_json=>serialize( data = ls_response ).
+   ```
+
+3. **Test class name max 30 chars**: `ltcl_util` (not `ltcl_abgagt_util_test`)
+
+4. **Interface method implementation**: Use prefix `zif_interface~method_name`
+
+---
+
+## Error Handling
+
+- **"Error updating where-used list"** → This is a **SYNTAX ERROR** (not a warning!)
+- Use `abapgit-agent inspect --files <file>` for detailed error messages with line numbers
+
+---
+
+## Guidelines Index
+
+Detailed guidelines are available in the `guidelines/` folder:
+
+| File | Topic |
+|------|-------|
+| `../guidelines/01_sql.md` | ABAP SQL Best Practices |
+| `../guidelines/02_exceptions.md` | Exception Handling |
+| `../guidelines/03_testing.md` | Unit Testing (including CDS) |
+| `../guidelines/04_cds.md` | CDS Views |
+| `../guidelines/05_classes.md` | ABAP Classes and Objects |
+| `../guidelines/06_objects.md` | Object Naming Conventions |
+| `../guidelines/07_json.md` | JSON Handling |
+| `../guidelines/08_abapgit.md` | abapGit XML Metadata Templates |
+
+These guidelines are automatically searched by the `ref` command.
+
+---
+
+## Object Naming
+
+| Pattern | Type |
+|---------|------|
+| `ZCL_*` | Class |
+| `ZIF_*` | Interface |
+| `Z*` | Other objects |

package/abap/CLAUDE.md

@@ -0,0 +1,313 @@
+# ABAP Project Guidelines - Template
+
+This file provides guidelines for **generating ABAP code** in abapGit repositories.
+
+**Use this file as a template**: Copy it to your ABAP repository root when setting up new projects with Claude Code.
+
+---
+
+## Critical Rules
+
+### 1. Use `ref` Command for Unfamiliar Topics
+
+**When starting to work on ANY unfamiliar ABAP topic, syntax, or pattern, you MUST use the `ref` command BEFORE writing any code.**
+
+```
+❌ WRONG: Start writing code immediately based on assumptions
+✅ CORRECT: Run ref command first to look up the correct pattern
+```
+
+**Why**: ABAP syntax is strict. Guessing leads to activation errors that waste time.
+
+| Scenario | Example |
+|----------|---------|
+| Implementing new ABAP feature | "How do I use FILTER operator?" |
+| Unfamiliar pattern | "What's the correct VALUE #() syntax?" |
+| SQL operations | "How to write a proper SELECT with JOIN?" |
+| CDS views | "How to define CDS view with associations?" |
+| Getting syntax errors | Check reference before trying approaches |
+
+```bash
+# For CDS topics
+abapgit-agent ref --topic cds
+abapgit-agent ref "CDS view"
+abapgit-agent ref "association"
+```
+
+```bash
+# Search for a pattern
+abapgit-agent ref "CORRESPONDING"
+abapgit-agent ref "FILTER #"
+
+# Browse by topic
+abapgit-agent ref --topic exceptions
+abapgit-agent ref --topic sql
+
+# List all topics
+abapgit-agent ref --list-topics
+```
+
+### 2. Read `.abapGitAgent` for Folder Location
+
+**Before creating ANY ABAP object file, you MUST read `.abapGitAgent` to determine the correct folder.**
+
+```
+❌ WRONG: Assume files go in "abap/" folder
+✅ CORRECT: Read .abapGitAgent to get the "folder" property value
+```
+
+The folder is configured in `.abapGitAgent` (property: `folder`):
+- If `folder` is `/src/` → files go in `src/` (e.g., `src/zcl_my_class.clas.abap`)
+- If `folder` is `/abap/` → files go in `abap/` (e.g., `abap/zcl_my_class.clas.abap`)
+
+---
+
+### 3. Create XML Metadata for Each ABAP Object
+
+**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` |
+
+**Use `ref --topic abapgit` for complete XML templates.**
+
+---
+
+### 4. NEVER Run Inspect Before Push/Pull (MOST IMPORTANT!)
+
+```
+❌ WRONG: Make changes → Run inspect → Check errors → Repeat
+✅ CORRECT: Make changes → Commit → Push → Run pull → Then inspect ONLY if pull fails
+```
+
+**Why**: Inspect runs against the ABAP system, not git. The code must be in git and pulled to ABAP first.
+
+---
+
+### 5. Local Classes (Test Doubles, Helpers)
+
+When a class needs local helper classes or test doubles, use separate files:
+
+| File | Purpose |
+|------|---------|
+| `zcl_xxx.clas.locals_def.abap` | Local class definitions |
+| `zcl_xxx.clas.locals_imp.abap` | Local class implementations |
+
+**XML Configuration**: Add `<CLSCCINCL>X</CLSCCINCL>` to the class XML to include local class definitions:
+
+```xml
+<VSEOCLASS>
+  <CLSNAME>ZCL_XXX</CLSNAME>
+  ...
+  <CLSCCINCL>X</CLSCCINCL>
+</VSEOCLASS>
+```
+
+### 6. Use `ref`, `view` and `where` Commands to Learn About Unknown Classes/Methods
+
+**When working with unfamiliar ABAP classes or methods, follow this priority:**
+
+```
+1. First: Check local git repo for usage examples
+2. Second: Check ABAP reference/cheat sheets
+3. Third: Use view/where commands to query ABAP system (if needed)
+```
+
+#### Priority 1: Check Local Git Repository
+
+**Look for usage examples in your local ABAP project first:**
+- Search for class/interface names in your codebase
+- Check how similar classes are implemented
+- This gives the most relevant context for your project
+
+#### Priority 2: Check ABAP References
+
+```bash
+# Search in ABAP cheat sheets and guidelines
+abapgit-agent ref "CLASS"
+abapgit-agent ref "INTERFACE"
+abapgit-agent ref --topic classes
+```
+
+#### Priority 3: Use `where` and `view` Commands (Query ABAP System)
+
+**If local/references don't have the answer, query the ABAP system:**
+
+```bash
+# Find where a class/interface is USED (where command)
+abapgit-agent where --objects ZIF_UNKNOWN_INTERFACE
+
+# With pagination (default limit: 50, offset: 0)
+abapgit-agent where --objects ZIF_UNKNOWN_INTERFACE --limit 20
+abapgit-agent where --objects ZIF_UNKNOWN_INTERFACE --offset 50 --limit 20
+
+# View CLASS DEFINITION (view command)
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS
+
+# View specific METHOD implementation
+abapgit-agent view --objects ZCL_UNKNOWN_CLASS=============CM001
+```
+
+**Example workflow for AI:**
+```
+User: "How do I use ZCL_ABGAGT_AGENT?"
+
+AI thought process:
+1. Search local repo for ZCL_ABGAGT_AGENT usage
+2. Found: It's instantiated in several places with ->pull() method
+3. Still unclear about parameters? Check view command
+4. View: abapgit-agent view --objects ZCL_ABGAGT_AGENT
+```
+
+**Key differences:**
+- `where`: Shows WHERE an object is USED (references)
+- `view`: Shows what an object DEFINES (structure, methods, source)
+
+---
+
+### 7. Use CDS Test Double Framework for CDS View Tests
+
+**When creating unit tests for CDS views, use the CDS Test Double Framework (`CL_CDS_TEST_ENVIRONMENT`).**
+
+```
+❌ WRONG: Use regular AUnit test class without test doubles
+✅ CORRECT: Use CL_CDS_TEST_ENVIRONMENT to create test doubles for CDS views
+```
+
+**Why**: CDS views read from database tables. Using test doubles allows:
+- Injecting test data without affecting production data
+- Testing specific scenarios that may not exist in production
+- Fast, isolated tests that don't depend on database state
+
+See `guidelines/03_testing.md` for code examples.
+
+---
+
+### 8. Use `unit` Command for Unit Tests
+
+**Use `abapgit-agent unit` to run ABAP unit tests (AUnit).**
+
+```
+❌ WRONG: Try to use SE24, SE37, or other transaction codes
+✅ CORRECT: Use abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
+```
+
+```bash
+# Run unit tests (after pulling to ABAP)
+abapgit-agent unit --files src/zcl_test.clas.testclasses.abap
+
+# Multiple test classes
+abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
+```
+
+---
+
+## Development Workflow
+
+```
+1. Read .abapGitAgent → get folder value
+       │
+       ▼
+2. Research → use ref command for unfamiliar topics
+       │
+       ▼
+3. Write code → place in correct folder (e.g., src/zcl_*.clas.abap)
+       │
+       ▼
+4. Commit and push → git add . && git commit && git push
+       │
+       ▼
+5. Activate → abapgit-agent pull --files src/file.clas.abap
+       │
+       ▼
+6. Verify → Check pull output
+   - **Do NOT run inspect before commit/push/pull** - ABAP validates on pull
+   - **Do NOT run unit before pull** - Tests run against ABAP system, code must be activated first
+   - **"Error updating where-used list"** → This is a **SYNTAX ERROR** (check inspect for details)
+   - Objects NOT in "Activated Objects" but in "Failed Objects Log" → Syntax error (check inspect)
+   - Objects NOT appearing at all → XML metadata issue (check XML format in 08_abapgit.md)
+       │
+       ▼
+7. (Optional) Run unit tests → abapgit-agent unit --files src/zcl_test.clas.testclasses.abap (ONLY if test file exists, AFTER successful pull)
+       │
+       ▼
+8. If needed → Use inspect to check syntax (runs against ABAP system)
+```
+
+**IMPORTANT**:
+- **ALWAYS push to git BEFORE running pull** - abapGit reads from git
+- **Use inspect AFTER pull** to check syntax on objects already in ABAP
+- **Check pull output**:
+  - In "Failed Objects Log" → Syntax error (use inspect for details)
+  - Not appearing at all → XML metadata is wrong
+
+**When to use inspect vs view**:
+- **inspect**: Use when there are SYNTAX ERRORS (to find line numbers and details)
+- **view**: Use when you need to understand an object STRUCTURE (table fields, class methods)
+- Do NOT use view to debug syntax errors - view shows definitions, not errors
+
+### Commands
+
+```bash
+# 1. Pull/activate after pushing to git (abapGit reads from git!)
+abapgit-agent pull --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap
+
+# 2. Inspect AFTER pull to check syntax (runs against ABAP system)
+abapgit-agent inspect --files src/zcl_class1.clas.abap
+
+# Run unit tests (multiple test classes)
+abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
+
+# View object definitions (multiple objects)
+abapgit-agent view --objects ZCL_CLASS1,ZCL_CLASS2,ZIF_INTERFACE
+
+# Preview table data (multiple tables/views)
+abapgit-agent preview --objects ZTABLE1,ZTABLE2
+
+# Explore table structures
+abapgit-agent view --objects ZTABLE --type TABL
+
+# Display package tree
+abapgit-agent tree --package \$MY_PACKAGE
+```
+
+---
+
+## Guidelines Index
+
+Detailed guidelines are available in the `guidelines/` folder:
+
+| File | Topic |
+|------|-------|
+| `guidelines/01_sql.md` | ABAP SQL Best Practices |
+| `guidelines/02_exceptions.md` | Exception Handling |
+| `guidelines/03_testing.md` | Unit Testing (including CDS) |
+| `guidelines/04_cds.md` | CDS Views |
+| `guidelines/05_classes.md` | ABAP Classes and Objects |
+| `guidelines/06_objects.md` | Object Naming Conventions |
+| `guidelines/07_json.md` | JSON Handling |
+| `guidelines/08_abapgit.md` | abapGit XML Metadata Templates |
+
+These guidelines are automatically searched by the `ref` command.
+
+---
+
+## Custom Guidelines
+
+You can add your own guidelines:
+
+1. Create `.md` files in `guidelines/` folder
+2. Export to reference folder: `abapgit-agent ref export`
+3. The `ref` command will search both cheat sheets and your custom guidelines
+
+---
+
+## For More Information
+
+- [SAP ABAP Cheat Sheets](https://github.com/SAP-samples/abap-cheat-sheets)
+- [ABAP Keyword Documentation](https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm)

package/bin/abapgit-agent

@@ -2305,10 +2305,11 @@ Examples:
         const objectsArgIndex = args.indexOf('--objects');
         if (objectsArgIndex === -1 || objectsArgIndex + 1 >= args.length) {
           console.error('Error: --objects parameter required');
-          console.error('Usage: abapgit-agent preview --objects <table1>,<view1>,... [--type <type>] [--limit <n>] [--where <condition>] [--columns <cols>] [--vertical] [--compact] [--json]');
+          console.error('Usage: abapgit-agent preview --objects <table1>,<view1>,... [--type <type>] [--limit <n>] [--offset <n>] [--where <condition>] [--columns <cols>] [--vertical] [--compact] [--json]');
           console.error('Example: abapgit-agent preview --objects SFLIGHT');
           console.error('Example: abapgit-agent preview --objects ZC_MY_CDS_VIEW --type DDLS');
           console.error('Example: abapgit-agent preview --objects SFLIGHT --where "CARRID = \'AA\'"');
+          console.error('Example: abapgit-agent preview --objects SFLIGHT --offset 10 --limit 20');
           process.exit(1);
         }
 
@@ -2316,7 +2317,13 @@ Examples:
         const typeArg = args.indexOf('--type');
         const type = typeArg !== -1 ? args[typeArg + 1].toUpperCase() : null;
         const limitArg = args.indexOf('--limit');
-        const limit = limitArg !== -1 ? parseInt(args[limitArg + 1], 10) : 10;
+        const limitRaw = limitArg !== -1 ? args[limitArg + 1] : null;
+        const limitParsed = parseInt(limitRaw, 10);
+        const limit = limitRaw && !limitRaw.startsWith('--') && !isNaN(limitParsed) ? Math.max(1, limitParsed) : 100;
+        const offsetArg = args.indexOf('--offset');
+        const offsetRaw = offsetArg !== -1 ? args[offsetArg + 1] : null;
+        const offsetParsed = parseInt(offsetRaw, 10);
+        const offset = offsetRaw && !offsetRaw.startsWith('--') && !isNaN(offsetParsed) ? Math.max(0, offsetParsed) : 0;
         const whereArg = args.indexOf('--where');
         const where = whereArg !== -1 ? args[whereArg + 1] : null;
         const columnsArg = args.indexOf('--columns');
@@ -2332,7 +2339,8 @@ Examples:
 
         const data = {
           objects: objects,
-          limit: Math.min(Math.max(1, limit), 100)
+          limit: Math.min(Math.max(1, limit), 500),
+          offset: Math.max(0, offset)
         };
 
         if (type) {
@@ -2360,10 +2368,30 @@ Examples:
           break;
         }
 
+        const pagination = result.PAGINATION || result.pagination || null;
+
         if (jsonOutput) {
           console.log(JSON.stringify(result, null, 2));
         } else {
-          console.log(`\n  ${message}`);
+          // Build pagination message
+          let paginationMsg = '';
+          const paginationTotal = pagination ? (pagination.TOTAL || pagination.total || 0) : 0;
+          const paginationHasMore = pagination ? (pagination.HAS_MORE || pagination.has_more || false) : false;
+          if (pagination && paginationTotal > 0) {
+            // Handle case where offset exceeds total
+            if (offset >= paginationTotal) {
+              paginationMsg = ` (Offset ${offset} exceeds total ${paginationTotal})`;
+            } else {
+              const start = offset + 1;
+              const end = Math.min(offset + limit, paginationTotal);
+              paginationMsg = ` (Showing ${start}-${end} of ${paginationTotal})`;
+              if (paginationHasMore) {
+                paginationMsg += ` — Use --offset ${offset + limit} to see more`;
+              }
+            }
+          }
+
+          console.log(`\n  ${message}${paginationMsg}`);
           console.log('');
 
           // Track if columns were explicitly specified
@@ -2542,10 +2570,11 @@ Examples:
         const objectsArgIndex = args.indexOf('--objects');
         if (objectsArgIndex === -1 || objectsArgIndex + 1 >= args.length) {
           console.error('Error: --objects parameter required');
-          console.error('Usage: abapgit-agent where --objects <obj1>,<obj2>,... [--type <type>] [--limit <n>] [--json]');
+          console.error('Usage: abapgit-agent where --objects <obj1>,<obj2>,... [--type <type>] [--limit <n>] [--offset <n>] [--json]');
           console.error('Example: abapgit-agent where --objects ZCL_MY_CLASS');
           console.error('Example: abapgit-agent where --objects ZIF_MY_INTERFACE');
           console.error('Example: abapgit-agent where --objects CL_SUT_AUNIT_RUNNER --limit 20');
+          console.error('Example: abapgit-agent where --objects CL_SUT_AUNIT_RUNNER --offset 100');
           process.exit(1);
         }
 
@@ -2553,7 +2582,13 @@ Examples:
         const typeArg = args.indexOf('--type');
         const type = typeArg !== -1 ? args[typeArg + 1].toUpperCase() : null;
         const limitArg = args.indexOf('--limit');
-        const limit = limitArg !== -1 ? parseInt(args[limitArg + 1], 10) : 100;
+        const limitRaw = limitArg !== -1 ? args[limitArg + 1] : null;
+        const limitParsed = parseInt(limitRaw, 10);
+        const limit = limitRaw && !limitRaw.startsWith('--') && !isNaN(limitParsed) ? Math.max(1, limitParsed) : 100;
+        const offsetArg = args.indexOf('--offset');
+        const offsetRaw = offsetArg !== -1 ? args[offsetArg + 1] : null;
+        const offsetParsed = parseInt(offsetRaw, 10);
+        const offset = offsetRaw && !offsetRaw.startsWith('--') && !isNaN(offsetParsed) ? Math.max(0, offsetParsed) : 0;
         const jsonOutput = args.includes('--json');
 
         console.log(`\n  Where-used list for ${objects.length} object(s)`);
@@ -2563,7 +2598,8 @@ Examples:
 
         const data = {
           objects: objects,
-          limit: Math.min(Math.max(1, limit), 500)
+          limit: Math.min(Math.max(1, limit), 500),
+          offset: Math.max(0, offset)
         };
 
         if (type) {
@@ -2577,6 +2613,7 @@ Examples:
         const whereObjects = result.OBJECTS || result.objects || [];
         const message = result.MESSAGE || result.message || '';
         const error = result.ERROR || result.error;
+        const pagination = result.PAGINATION || result.pagination || null;
 
         if (!success || error) {
           console.error(`\n  Error: ${error || 'Failed to get where-used list'}`);
@@ -2586,7 +2623,25 @@ Examples:
         if (jsonOutput) {
           console.log(JSON.stringify(result, null, 2));
         } else {
-          console.log(`\n  ${message}`);
+          // Build pagination message
+          let paginationMsg = '';
+          const paginationTotal = pagination.TOTAL || pagination.total || 0;
+          const paginationHasMore = pagination.HAS_MORE || pagination.has_more || false;
+          if (pagination && paginationTotal > 0) {
+            // Handle case where offset exceeds total
+            if (offset >= paginationTotal) {
+              paginationMsg = ` (Offset ${offset} exceeds total ${paginationTotal})`;
+            } else {
+              const start = offset + 1;
+              const end = Math.min(offset + limit, paginationTotal);
+              paginationMsg = ` (Showing ${start}-${end} of ${paginationTotal})`;
+              if (paginationHasMore) {
+                paginationMsg += ` — Use --offset ${offset + limit} to see more`;
+              }
+            }
+          }
+
+          console.log(`\n  ${message}${paginationMsg}`);
           console.log('');
 
           for (let i = 0; i < whereObjects.length; i++) {
@@ -2640,17 +2695,21 @@ Examples:
       case 'ref': {
         const refSearch = require('../src/ref-search');
         const topicIndex = args.indexOf('--topic');
+        const cloneIndex = args.indexOf('--clone');
+        const nameIndex = args.indexOf('--name');
         const listTopics = args.includes('--list-topics') || args.includes('-l');
         const listRepos = args.includes('--list-repos') || args.includes('-r');
-        const exportGuidelines = args.includes('--export') || args.includes('-e');
         const jsonOutput = args.includes('--json');
 
-        if (exportGuidelines) {
-          const result = await refSearch.exportGuidelines();
+        // Handle --clone option
+        if (cloneIndex !== -1 && cloneIndex + 1 < args.length) {
+          const repoUrl = args[cloneIndex + 1];
+          const name = nameIndex !== -1 && nameIndex + 1 < args.length ? args[nameIndex + 1] : null;
+          const result = refSearch.cloneRepository(repoUrl, name);
           if (jsonOutput) {
             console.log(JSON.stringify(result, null, 2));
           } else {
-            refSearch.displayExportResult(result);
+            refSearch.displayCloneResult(result);
           }
           break;
         }
@@ -2695,15 +2754,16 @@ Examples:
           console.error('  abapgit-agent ref <pattern>           Search for pattern');
           console.error('  abapgit-agent ref --topic <name>      View specific topic');
           console.error('  abapgit-agent ref --list-topics       List available topics');
-          console.error('  abapgit-agent ref --list-repos        List reference repositories');
-          console.error('  abapgit-agent ref --export            Export local guidelines to reference folder');
+          console.error('  abapgit-agent ref --list-repos       List reference repositories');
+          console.error('  abapgit-agent ref --clone <repo>     Clone a repository');
           console.error('');
           console.error('Examples:');
           console.error('  abapgit-agent ref "CORRESPONDING"');
           console.error('  abapgit-agent ref --topic exceptions');
           console.error('  abapgit-agent ref --list-topics');
           console.error('  abapgit-agent ref --list-repos');
-          console.error('  abapgit-agent ref --export');
+          console.error('  abapgit-agent ref --clone SAP-samples/abap-cheat-sheets');
+          console.error('  abapgit-agent ref --clone https://github.com/abapGit/abapGit.git');
           process.exit(1);
         }
 
@@ -2777,8 +2837,10 @@ Commands:
   ref --list-repos
     List all reference repositories in the reference folder
 
-  ref --export
-    Export custom guidelines (abap/guidelines/) to reference folder
+  ref --clone <repo> [--name <folder>]
+    Clone a GitHub repository to the reference folder
+    - Use full URL: https://github.com/user/repo.git
+    - Or short name: user/repo or user/repo (assumes github.com)
 
   health
     Check if ABAP REST API is healthy
@@ -2823,7 +2885,8 @@ Examples:
   abapgit-agent ref --topic unit-tests                       # View unit test topic
   abapgit-agent ref --list-topics                            # List all topics
   abapgit-agent ref --list-repos                             # List reference repositories
-  abapgit-agent ref --export                                  # Export custom guidelines
+  abapgit-agent ref --clone SAP-samples/abap-cheat-sheets    # Clone repo to reference folder
+  abapgit-agent ref --clone https://github.com/user/repo.git # Clone from URL
   abapgit-agent health
   abapgit-agent status
 `);

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "abapgit-agent",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [
     "bin/",
     "src/",
-    "abap/guidelines/"
+    "abap/guidelines/",
+    "abap/CLAUDE.md",
+    "abap/.github/copilot-instructions.md",
+    ".abapGitAgent.example"
   ],
   "bin": {
     "abapgit-agent": "bin/abapgit-agent",
@@ -20,6 +23,7 @@
     "test:jest": "jest",
     "test:aunit": "node scripts/test-all.js --aunit",
     "test:cmd": "node scripts/test-all.js --cmd",
+    "test:cmd:demo": "node scripts/test-all.js --cmd --demo",
     "pull": "node bin/abapgit-agent",
     "release": "node scripts/release.js",
     "unrelease": "node scripts/unrelease.js"

package/src/abap-client.js

@@ -379,13 +379,14 @@ class ABAPClient {
     return await this.request('POST', '/tree', data, { csrfToken: this.csrfToken });
   }
 
-  async preview(objects, type = null, limit = 10, where = null, columns = null) {
+  async preview(objects, type = null, limit = 100, offset = 0, where = null, columns = null) {
     // Fetch CSRF token first
     await this.fetchCsrfToken();
 
     const data = {
       objects: objects,
-      limit: Math.min(Math.max(1, limit), 100)
+      limit: Math.min(Math.max(1, limit), 500),
+      offset: Math.max(0, offset)
     };
 
     if (type) {
@@ -402,7 +403,7 @@ class ABAPClient {
       data.columns = columns;
     }
 
-    logger.info('Previewing data', { objects, type, limit: data.limit, where: data.where, service: 'abapgit-agent' });
+    logger.info('Previewing data', { objects, type, limit: data.limit, offset: data.offset, where: data.where, service: 'abapgit-agent' });
 
     return await this.request('POST', '/preview', data, { csrfToken: this.csrfToken });
   }
@@ -487,21 +488,23 @@ class ABAPClient {
    * @param {Array} objects - Array of object names to search
    * @param {string} type - Object type (optional)
    * @param {number} limit - Maximum results (default: 100, max: 500)
+   * @param {number} offset - Number of results to skip (default: 0)
    * @returns {object} Where-used result with found objects
    */
-  async where(objects, type = null, limit = 100) {
+  async where(objects, type = null, limit = 100, offset = 0) {
     await this.fetchCsrfToken();
 
     const data = {
       objects: objects,
-      limit: Math.min(Math.max(1, limit), 500)
+      limit: Math.min(Math.max(1, limit), 500),
+      offset: Math.max(0, offset)
     };
 
     if (type) {
       data.type = type;
     }
 
-    logger.info('Finding where-used', { objects, type, limit: data.limit, service: 'abapgit-agent' });
+    logger.info('Finding where-used', { objects, type, limit: data.limit, offset: data.offset, service: 'abapgit-agent' });
 
     return await this.request('POST', '/where', data, { csrfToken: this.csrfToken });
   }

package/src/agent.js

@@ -197,21 +197,23 @@ class ABAPGitAgent {
    * @param {Array} objects - Array of table/view names
    * @param {string} type - Object type (TABL, DDLS, etc.)
    * @param {number} limit - Maximum rows to return
+   * @param {number} offset - Number of rows to skip
    * @param {string} where - WHERE clause filter
    * @param {Array} columns - Array of column names to display
    * @returns {object} Preview result with rows, fields, and metadata
    */
-  async preview(objects, type = null, limit = 10, where = null, columns = null) {
-    logger.info('Previewing data', { objects, type, limit, where, columns });
+  async preview(objects, type = null, limit = 100, offset = 0, where = null, columns = null) {
+    logger.info('Previewing data', { objects, type, limit, offset, where, columns });
 
     try {
-      const result = await this.abap.preview(objects, type, limit, where, columns);
+      const result = await this.abap.preview(objects, type, limit, offset, where, columns);
       return {
         success: result.SUCCESS === 'X' || result.success === 'X' || result.success === true,
         command: result.COMMAND || result.command || 'PREVIEW',
         message: result.MESSAGE || result.message || '',
         objects: result.OBJECTS || result.objects || [],
         summary: result.SUMMARY || result.summary || null,
+        pagination: result.PAGINATION || result.pagination || null,
         error: result.ERROR || result.error || null
       };
     } catch (error) {
@@ -293,18 +295,20 @@ class ABAPGitAgent {
    * @param {Array} objects - Array of object names to search
    * @param {string} type - Object type (optional)
    * @param {number} limit - Maximum results (default: 100, max: 500)
+   * @param {number} offset - Number of results to skip (default: 0)
    * @returns {object} Where-used result with found objects
    */
-  async where(objects, type = null, limit = 100) {
-    logger.info('Finding where-used', { objects, type, limit });
+  async where(objects, type = null, limit = 100, offset = 0) {
+    logger.info('Finding where-used', { objects, type, limit, offset });
 
     try {
-      const result = await this.abap.where(objects, type, limit);
+      const result = await this.abap.where(objects, type, limit, offset);
       return {
         success: result.SUCCESS === 'X' || result.success === 'X' || result.success === true,
         command: result.COMMAND || result.command || 'WHERE',
         objects: result.OBJECTS || result.objects || [],
         message: result.MESSAGE || result.message || '',
+        pagination: result.PAGINATION || result.pagination || null,
         error: result.ERROR || result.error || null
       };
     } catch (error) {

package/src/ref-search.js

@@ -8,6 +8,7 @@
 const fs = require('fs');
 const path = require('path');
 const { promisify } = require('util');
+const { execSync } = require('child_process');
 const readdir = promisify(fs.readdir);
 const readFile = promisify(fs.readFile);
 const stat = promisify(fs.stat);
@@ -63,6 +64,120 @@ const TOPIC_MAP = {
   'tables': '01_Internal_Tables.md'
 };
 
+/**
+ * Ensure reference folder exists, create if necessary
+ * @returns {string|null} Path to reference folder or null if cannot create
+ */
+function ensureReferenceFolder() {
+  let refFolder = detectReferenceFolder();
+
+  if (refFolder && fs.existsSync(refFolder)) {
+    return refFolder;
+  }
+
+  // Try to create the reference folder at default location
+  const homeDir = require('os').homedir();
+  const defaultPath = path.join(homeDir, 'abap-reference');
+
+  try {
+    if (!fs.existsSync(defaultPath)) {
+      fs.mkdirSync(defaultPath, { recursive: true });
+    }
+    return defaultPath;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Clone a repository to the reference folder
+ * @param {string} repoUrl - Git repository URL or short name (e.g., "SAP-samples/abap-cheat-sheets")
+ * @param {string|null} name - Optional folder name for the cloned repo
+ * @returns {Object} Clone result
+ */
+function cloneRepository(repoUrl, name = null) {
+  const refFolder = ensureReferenceFolder();
+
+  if (!refFolder) {
+    return {
+      success: false,
+      error: 'Could not create reference folder',
+      hint: 'Set referenceFolder in .abapGitAgent or ensure ~/abap-reference is writable'
+    };
+  }
+
+  // Parse the repo URL
+  let targetName = name;
+  let cloneUrl = repoUrl;
+
+  // Handle short names (e.g., "SAP-samples/abap-cheat-sheets")
+  if (!repoUrl.startsWith('http://') && !repoUrl.startsWith('https://') && !repoUrl.startsWith('git@')) {
+    cloneUrl = `https://github.com/${repoUrl}.git`;
+  }
+
+  // If no name provided, extract from URL
+  if (!targetName) {
+    // Extract repo name from URL
+    const urlParts = cloneUrl.split('/');
+    const repoWithGit = urlParts[urlParts.length - 1];
+    targetName = repoWithGit.replace(/\.git$/, '');
+  }
+
+  const targetPath = path.join(refFolder, targetName);
+
+  // Check if already exists
+  if (fs.existsSync(targetPath)) {
+    return {
+      success: false,
+      error: `Repository already exists: ${targetName}`,
+      hint: `Delete '${targetPath}' to re-clone, or use --name to specify a different folder name`,
+      existingPath: targetPath
+    };
+  }
+
+  try {
+    // Run git clone
+    execSync(`git clone "${cloneUrl}" "${targetPath}"`, {
+      stdio: 'pipe',
+      encoding: 'utf8'
+    });
+
+    return {
+      success: true,
+      message: `Successfully cloned ${repoUrl}`,
+      repository: targetName,
+      folder: targetPath,
+      referenceFolder: refFolder
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to clone: ${error.message}`,
+      hint: 'Check the repository URL and your network connection'
+    };
+  }
+}
+
+/**
+ * Display clone result in console format
+ * @param {Object} result - Clone result
+ */
+function displayCloneResult(result) {
+  if (result.success) {
+    console.log(`\n  ✅ ${result.message}`);
+    console.log(`\n  📁 Repository: ${result.repository}`);
+    console.log(`  📁 Location: ${result.folder}`);
+    console.log(`  📁 Reference folder: ${result.referenceFolder}`);
+    console.log(`\n  💡 You can now search this repository with:`);
+    console.log(`     abapgit-agent ref --list-repos`);
+  } else {
+    console.error(`\n  ❌ ${result.error}`);
+    if (result.hint) {
+      console.error(`\n  💡 ${result.hint}`);
+    }
+  }
+}
+
 /**
  * Detect reference folder from config or common locations
  * @returns {string|null} Path to reference folder or null if not found
@@ -1005,7 +1120,7 @@ function displayInitResult(result) {
     console.log(`\n  💡 Next steps:`);
     console.log(`    1. Review the guidelines in abap/guidelines/`);
     console.log(`    2. Customize as needed for your project`);
-    console.log(`    3. Run 'abapgit-agent ref --export' to make them searchable`);
+    console.log(`    3. Guidelines are automatically searchable with 'ref' command`);
   } else {
     console.error(`\n  ❌ ${result.error}`);
     if (result.hint) {
@@ -1016,6 +1131,7 @@ function displayInitResult(result) {
 
 module.exports = {
   detectReferenceFolder,
+  ensureReferenceFolder,
   detectGuidelinesFolder,
   getBuiltInGuidelinesPath,
   initGuidelines,
@@ -1027,11 +1143,13 @@ module.exports = {
   listTopics,
   listRepositories,
   exportGuidelines,
+  cloneRepository,
   displaySearchResults,
   displayTopic,
   displayTopics,
   displayRepositories,
   displayExportResult,
   displayInitResult,
+  displayCloneResult,
   TOPIC_MAP
 };