abapgit-agent 1.16.0 → 1.16.2

package/abap/CLAUDE.md

@@ -494,7 +494,16 @@ Never assume — wait for the user's answer before proceeding.
 
 **Critical rules for `debug` sessions:**
 
-1. **Always use `--json`** for all debug commands (`attach`, `vars`, `stack`, `step`) — human output is not machine-parseable
+```
+❌ WRONG: abapgit-agent debug attach
+❌ WRONG: abapgit-agent debug vars
+❌ WRONG: abapgit-agent debug step --type continue
+✅ CORRECT: abapgit-agent debug attach --json > /tmp/a.json 2>&1 &
+✅ CORRECT: abapgit-agent debug vars --json
+✅ CORRECT: abapgit-agent debug step --type continue --json
+```
+
+1. **Always use `--json`** for ALL debug commands (`attach`, `vars`, `stack`, `step`) — human output is not machine-parseable. This is non-negotiable.
 2. **Attach BEFORE trigger** — start `debug attach --json` in background first, wait for `"Listener active"`, THEN fire the trigger (`unit`/`pull`/`run`)
 3. **Never pull to trigger** if a simpler trigger works — use `unit` when a test exists, `run` for a class runner; use `pull` only when the bug is specifically in the pull flow
 4. **Never pass `--session`** to `step/vars/stack` — it bypasses the daemon and causes errors
@@ -502,7 +511,12 @@ Never assume — wait for the user's answer before proceeding.
 
 **Finding the right line number for a breakpoint:**
 
-Use `view --full --lines` to get ready-to-use `debug set` commands per method:
+```
+❌ WRONG: abapgit-agent debug set --objects ZCL_FOO:42   ← never guess a line number
+✅ CORRECT: abapgit-agent view --objects ZCL_FOO --full --lines   ← get exact line from output
+```
+
+Always run `view --full --lines` first — it prints a ready-to-use `debug set` command for every method. Never guess or estimate line numbers.
 
 ```bash
 abapgit-agent view --objects ZCL_FOO --full --lines
@@ -542,7 +556,8 @@ abapgit-agent debug set --objects LSUSRU04:50
 
 Minimal correct sequence:
 ```bash
-abapgit-agent debug set --objects ZCL_FOO:42        # 1. set breakpoint
+abapgit-agent view --objects ZCL_FOO --full --lines  # 0. get exact line number from output hint
+abapgit-agent debug set --objects ZCL_FOO:42        # 1. set breakpoint (use line from step 0)
 abapgit-agent debug attach --json > /tmp/a.json 2>&1 &   # 2. attach (background)
 until grep -q "Listener active" /tmp/a.json 2>/dev/null; do sleep 0.3; done
 abapgit-agent unit --files src/zcl_foo.clas.testclasses.abap > /tmp/t.json 2>&1 &  # 3. trigger
@@ -555,7 +570,7 @@ abapgit-agent debug step --type continue --json     # 4. release
 
 ---
 
-### 12. abaplint — Static Analysis (Optional, Project-Controlled)
+### 13. abaplint — Static Analysis (Optional, Project-Controlled)
 
 abaplint is **optional**. Only run it if `.abaplint.json` exists in the project root.
 Each project defines its own rules — never assume which rules are active.
@@ -617,6 +632,7 @@ Checked into the repository — applies to all developers. **Read this file at t
 |---------|--------|---------|--------|
 | `safeguards.requireFilesForPull` | `true`/`false` | `false` | Requires `--files` on every pull |
 | `safeguards.disablePull` | `true`/`false` | `false` | Disables pull entirely (CI/CD-only projects) |
+| `safeguards.disableImport` | `true`/`false` | `false` | Disables import entirely (one-time or managed operation) |
 | `conflictDetection.mode` | `"abort"`/`"ignore"` | `"abort"` | Whether to abort pull on conflict |
 | `transports.hook.path` | string | `null` | Path to JS module that auto-selects a transport for pull |
 | `transports.hook.description` | string | `null` | Optional label shown when the hook runs |
@@ -709,6 +725,10 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 1. ✗ Do not run `abapgit-agent run` at all
 2. ✓ Inform the user that run is disabled for this project
 
+**When `safeguards.disableImport = true`:**
+1. ✗ Do not run `abapgit-agent import` at all
+2. ✓ Inform the user that import is disabled for this project
+
 **When `safeguards.disableProbeClasses = true`:**
 1. ✗ Do not create probe classes in the current project
 2. ✓ If `scratchWorkspace` is configured → create probe class there (see Rule 10)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "files": [
     "bin/",

package/src/commands/dump.js

@@ -196,6 +196,36 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent dump [--user <user>] [--date <date>] [--time <HH:MM..HH:MM>]
+                     [--program <prog>] [--error <error>] [--limit <n>] [--detail <n>] [--json]
+
+Description:
+  Query short dumps (ST22) from the ABAP system.
+
+Parameters:
+  --user <user>           Filter by user name.
+  --date <date>           Filter by date: TODAY, YESTERDAY, or YYYYMMDD or YYYYMMDD..YYYYMMDD.
+  --time <HH:MM..HH:MM>   Filter by time range (e.g. 08:00..17:00).
+  --program <prog>        Filter by program name.
+  --error <error>         Filter by error type (e.g. RABAX_STATE).
+  --timezone <tz>         Timezone for date/time filter (default: system timezone).
+  --limit <n>             Maximum number of results (default: 10).
+  --detail <n>            Show full detail of the Nth result (1-based).
+  --json                  Output as JSON.
+
+Examples:
+  abapgit-agent dump
+  abapgit-agent dump --date TODAY
+  abapgit-agent dump --user DEVELOPER
+  abapgit-agent dump --date TODAY --limit 20
+  abapgit-agent dump --user DEVELOPER --detail 1
+`);
+      return;
+    }
+
     const idx = (flag) => args.indexOf(flag);
     const val = (flag) => {
       const i = idx(flag);

package/src/commands/health.js

@@ -11,6 +11,18 @@ module.exports = {
   async execute(args, context) {
     const { config, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent health
+
+Description:
+  Check if the ABAP REST API (z_abapgit_agent) is reachable and responding.
+  Useful for verifying connectivity and configuration.
+`);
+      return;
+    }
+
     try {
       const http = new AbapHttp(config);
       const result = await http.get('/sap/bc/z_abapgit_agent/health');

package/src/commands/help.js

@@ -48,6 +48,24 @@ Commands:
   unit --files <file1>,<file2>,...
     Run AUnit tests for ABAP test class files (.testclasses.abap)
 
+  run --program <NAME> | --class <NAME>
+    Execute an ABAP program or class (IF_OO_ADT_CLASSRUN) and display its output.
+
+  drop --files <file> [--pull] [--transport <TRANSPORT>] [--conflict-mode <mode>]
+    Physically delete a single ABAP object from the ABAP system.
+    Use --pull to immediately re-activate from git after deletion.
+
+  lint [--files <file1,...>] [--base <branch>] [--config <file>]
+    Run abaplint static analysis on changed ABAP files. Requires .abaplint.json.
+
+  debug <subcommand> [options]
+    Manage ABAP debugger breakpoints and attach debug sessions.
+    Subcommands: set, list, delete, attach, step, vars, stack
+
+  transport <subcommand> [options]
+    List and manage SAP transport requests.
+    Subcommands: list, create, release
+
   tree --package <package> [--depth <n>] [--include-types] [--json]
     Display package hierarchy tree from ABAP system
 
@@ -57,6 +75,9 @@ Commands:
   view --objects <obj1>,<obj2>,... [--type <type>] [--json]
     View ABAP object definitions from the ABAP system
 
+  preview --objects <obj1>,... [--type <type>] [--limit <n>] [--where <cond>] [--json]
+    Preview data from ABAP tables or CDS views
+
   where --objects <obj1>,<obj2>,... [--type <type>] [--limit <n>] [--json]
     Find where-used list for ABAP objects (classes, interfaces, programs)
 
@@ -93,6 +114,9 @@ Commands:
     - Use --dry-run to preview changes without applying them
     - Use --yes to skip confirmation prompt
 
+  upgrade [--abap-only] [--cli-only] [--version <v>]
+    Upgrade CLI and/or ABAP backend to latest or specific version.
+
   health
     Check if ABAP REST API is healthy
 
@@ -114,9 +138,14 @@ Examples:
   abapgit-agent syntax --files src/zcl_my_class.clas.abap        # Check without pull
   abapgit-agent syntax --files src/zmy_prog.prog.abap --cloud    # ABAP Cloud check
   abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap  # Run unit tests
-  abapgit-agent tree --package $MY_PACKAGE                   # Display package tree
+  abapgit-agent run --program ZMY_REPORT                         # Execute report
+  abapgit-agent run --class ZCL_MY_RUNNER                        # Execute class
+  abapgit-agent drop --files src/zcl_foo.clas.abap --pull        # Drop and re-activate
+  abapgit-agent lint                                             # abaplint on changed files
+  abapgit-agent tree --package $MY_PACKAGE                       # Display package tree
   abapgit-agent list --package $MY_PACKAGE --type CLAS,INTF  # List classes & interfaces
   abapgit-agent view --objects ZCL_MY_CLASS                  # View class definition
+  abapgit-agent preview --objects SFLIGHT                    # Preview table data
   abapgit-agent where --objects ZCL_MY_CLASS                 # Find where class is used
   abapgit-agent dump --date TODAY                            # Recent short dumps
   abapgit-agent dump --user DEVELOPER --detail 1             # Full detail of first result
@@ -127,6 +156,8 @@ Examples:
   abapgit-agent health                                       # Health check
   abapgit-agent status                                       # Configuration status
 
+Run "abapgit-agent <command> --help" for detailed usage of any command.
+
 For more info: https://github.com/SylvosCai/abapgit-agent
 `);
   }

package/src/commands/import.js

@@ -18,7 +18,7 @@ module.exports = {
 
   async execute(args, context) {
     try {
-      const { loadConfig, gitUtils, AbapHttp } = context;
+      const { loadConfig, gitUtils, AbapHttp, getSafeguards } = context;
 
       // Show help if requested
     const helpIndex = args.findIndex(a => a === '--help' || a === '-h');
@@ -48,6 +48,18 @@ Examples:
       return;
     }
 
+    // Get parameters from config
+    const safeguards = getSafeguards();
+    if (safeguards.disableImport) {
+      console.error('❌ Error: import command is disabled for this project\n');
+      if (safeguards.reason) {
+        console.error(`Reason: ${safeguards.reason}\n`);
+      }
+      console.error('The import command has been disabled in .abapgit-agent.json');
+      console.error('Please contact the project maintainer to enable it.');
+      process.exit(1);
+    }
+
     // Get parameters from config
     const config = loadConfig();
     const repoUrl = gitUtils.getRemoteUrl();

package/src/commands/inspect.js

@@ -250,6 +250,29 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent inspect --files <file1>,<file2>,... [--variant <check-variant>] [--junit-output <file>] [--json]
+
+Description:
+  Run SAP Code Inspector checks on activated ABAP objects. Requires the objects
+  to be already active in the ABAP system (run pull first).
+
+Parameters:
+  --files <file1,...>       Comma-separated ABAP source files (required).
+  --variant <variant>       Code Inspector variant (default: system default).
+  --junit-output <file>     Write results as JUnit XML to this file.
+  --json                    Output as JSON.
+
+Examples:
+  abapgit-agent inspect --files src/zcl_my_class.clas.abap
+  abapgit-agent inspect --files src/zcl_my_class.clas.abap --variant ALL_CHECKS
+  abapgit-agent inspect --files src/zcl_my_class.clas.abap --junit-output reports/inspect.xml
+`);
+      return;
+    }
+
     const jsonOutput = args.includes('--json');
     const verbose = args.includes('--verbose');
     const filesArgIndex = args.indexOf('--files');

package/src/commands/lint.js

@@ -24,6 +24,32 @@ module.exports = {
   requiresAbapConfig: false,
 
   execute(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent lint [--files <file1,...>] [--base <branch>] [--config <file>]
+                     [--outformat <format>] [--outfile <file>]
+
+Description:
+  Run abaplint static analysis on changed ABAP files. Requires .abaplint.json in repo root.
+  By default detects files changed vs HEAD~1 (or vs --base branch).
+
+Parameters:
+  --files <file1,...>   Check specific files instead of auto-detecting changed files.
+  --base <branch>       Diff against this branch instead of HEAD~1 (e.g. main).
+  --config <file>       abaplint config file (default: .abaplint.json).
+  --outformat <format>  Output format: checkstyle (default: text).
+  --outfile <file>      Write output to file instead of stdout.
+
+Examples:
+  abapgit-agent lint
+  abapgit-agent lint --base main
+  abapgit-agent lint --files src/zcl_foo.clas.abap
+  abapgit-agent lint --outformat checkstyle --outfile reports/abaplint.xml
+`);
+      return;
+    }
+
     const configPath  = argValue(args, '--config')    || '.abaplint.json';
     const baseBranch  = argValue(args, '--base');
     const filesArg    = argValue(args, '--files');

package/src/commands/list.js

@@ -11,6 +11,31 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent list --package <package> [--type <types>] [--name <pattern>] [--limit <n>] [--offset <n>] [--json]
+
+Description:
+  List ABAP objects in a package with optional filtering and pagination.
+
+Parameters:
+  --package <package>   Package to list (required). Enclose $-packages in quotes.
+  --type <types>        Comma-separated object types to filter (e.g. CLAS,INTF).
+  --name <pattern>      Filter by object name pattern (e.g. ZCL_MY*).
+  --limit <n>           Maximum number of results (default: 100).
+  --offset <n>          Skip first N results (for pagination).
+  --json                Output as JSON.
+
+Examples:
+  abapgit-agent list --package ZMY_PACKAGE
+  abapgit-agent list --package ZMY_PACKAGE --type CLAS,INTF
+  abapgit-agent list --package ZMY_PACKAGE --name ZCL_MY*
+  abapgit-agent list --package ZMY_PACKAGE --limit 20 --offset 40
+`);
+      return;
+    }
+
     const packageArgIndex = args.indexOf('--package');
     if (packageArgIndex === -1) {
       console.error('Error: --package parameter required');

package/src/commands/preview.js

@@ -11,6 +11,36 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp, validators } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent preview --objects <obj1>,... [--type <type>] [--limit <n>] [--offset <n>]
+                        [--where <condition>] [--columns <cols>] [--vertical] [--compact] [--json]
+
+Description:
+  Preview data from ABAP tables or CDS views.
+
+Parameters:
+  --objects <obj1,...>   Comma-separated table/view names (required).
+  --type <type>          Object type: TABL, DDLS (auto-detected if omitted).
+  --limit <n>            Maximum number of rows (default: 20).
+  --offset <n>           Skip first N rows (for pagination).
+  --where <condition>    WHERE clause filter (e.g. "CARRID = 'AA'").
+  --columns <cols>       Comma-separated column names to display.
+  --vertical             Display each row vertically (field: value).
+  --compact              Compact output (no borders).
+  --json                 Output as JSON.
+
+Examples:
+  abapgit-agent preview --objects SFLIGHT
+  abapgit-agent preview --objects SFLIGHT --limit 5
+  abapgit-agent preview --objects SFLIGHT --where "CARRID = 'AA'"
+  abapgit-agent preview --objects ZC_MY_VIEW --type DDLS
+  abapgit-agent preview --objects SFLIGHT --offset 10 --limit 20
+`);
+      return;
+    }
+
     const objectsArgIndex = args.indexOf('--objects');
     if (objectsArgIndex === -1 || objectsArgIndex + 1 >= args.length) {
       console.error('Error: --objects parameter required');

package/src/commands/pull.js

@@ -42,6 +42,38 @@ module.exports = {
 
   async execute(args, context) {
     const { loadConfig, AbapHttp, gitUtils, getTransport, getSafeguards, getConflictSettings, getTransportSettings } = context;
+
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent pull [--url <git-url>] [--branch <branch>] [--files <file1,file2,...>]
+                     [--transport <TRANSPORT>] [--conflict-mode <mode>] [--sync-xml]
+
+Description:
+  Pull and activate ABAP objects from a git repository into the ABAP system.
+  Auto-detects git remote URL and branch from the current directory.
+
+Parameters:
+  --url <git-url>         Git repository URL. Auto-detected from git remote if omitted.
+  --branch <branch>       Branch to pull from. Auto-detected from current branch if omitted.
+  --files <file1,...>     Comma-separated list of files to pull (selective activation).
+  --transport <TRANSPORT> Transport request (e.g. DEVK900001).
+  --conflict-mode <mode>  Conflict handling: abort (default) or ignore.
+  --sync-xml              Rewrite XML metadata files to match ABAP serializer output.
+  --verbose               Show detailed activation output.
+
+Examples:
+  abapgit-agent pull
+  abapgit-agent pull --branch develop
+  abapgit-agent pull --files src/zcl_my_class.clas.abap
+  abapgit-agent pull --files src/zcl_foo.clas.abap,src/zif_foo.intf.abap
+  abapgit-agent pull --transport DEVK900001
+  abapgit-agent pull --conflict-mode ignore
+  abapgit-agent pull --files src/zcl_foo.clas.abap --sync-xml
+`);
+      return;
+    }
+
     const verbose = args.includes('--verbose');
     const syncXml = args.includes('--sync-xml');
 

package/src/commands/run.js

@@ -33,6 +33,27 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, getSafeguards } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent run --program <NAME>
+  abapgit-agent run --class <NAME>
+
+Description:
+  Execute an ABAP program or a class implementing IF_OO_ADT_CLASSRUN and display its output.
+
+Parameters:
+  --program <NAME>  Execute an ABAP report/program.
+  --class <NAME>    Execute a class implementing IF_OO_ADT_CLASSRUN (run method).
+  --json            Output as JSON.
+
+Examples:
+  abapgit-agent run --program ZMY_REPORT
+  abapgit-agent run --class ZCL_MY_RUNNER
+`);
+      return;
+    }
+
     // Check project-level safeguards
     const safeguards = getSafeguards();
     if (safeguards.disableRun) {

package/src/commands/status.js

@@ -13,6 +13,19 @@ module.exports = {
   async execute(args, context) {
     const { gitUtils, isAbapIntegrationEnabled, AbapHttp, loadConfig } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent status
+
+Description:
+  Check whether ABAP integration is configured for the current repository.
+  Shows the config location, SAP host, and whether the abapGit online repository
+  is registered in the ABAP system.
+`);
+      return;
+    }
+
     if (isAbapIntegrationEnabled()) {
       console.log('✅ ABAP Git Agent is ENABLED');
       console.log('   Config location:', pathModule.join(process.cwd(), '.abapGitAgent'));

package/src/commands/syntax.js

@@ -14,6 +14,28 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent syntax --files <file1>,<file2>,... [--cloud] [--json]
+
+Description:
+  Check syntax of local ABAP source files WITHOUT pulling or activating them.
+  Reads source from local files and checks directly in the ABAP system.
+
+Parameters:
+  --files <file1,...>  Comma-separated ABAP source files (required). Accepts CLAS, INTF, PROG.
+  --cloud              Use ABAP Cloud (BTP) stricter syntax check.
+  --json               Output as JSON.
+
+Examples:
+  abapgit-agent syntax --files src/zcl_my_class.clas.abap
+  abapgit-agent syntax --files src/zcl_foo.clas.abap,src/zif_foo.intf.abap
+  abapgit-agent syntax --files src/zmy_prog.prog.abap --cloud
+`);
+      return;
+    }
+
     const filesArgIndex = args.indexOf('--files');
     if (filesArgIndex === -1 || filesArgIndex + 1 >= args.length) {
       console.error('Error: --files parameter required');
@@ -49,6 +71,7 @@ module.exports = {
     // Group class files together (main + locals)
     const classFilesMap = new Map(); // className -> { main, locals_def, locals_imp }
     const fugrGroupMap = new Map();  // groupName -> { dir, fmFiles: Map<fmName, source> }
+    const progIncludeMap = new Map(); // includeName -> { filePath, source }
     const objects = [];
 
     for (const file of syntaxFiles) {
@@ -143,7 +166,7 @@ module.exports = {
           source: source
         };
 
-        // Read FIXPT from XML metadata for INTF and PROG
+        // Read FIXPT and SUBC from XML metadata for INTF and PROG
         if (objType === 'INTF' || objType === 'PROG') {
           const dir = pathModule.dirname(filePath);
           let xmlFile;
@@ -154,14 +177,22 @@ module.exports = {
           }
           if (xmlFile && fs.existsSync(xmlFile)) {
             const xmlContent = fs.readFileSync(xmlFile, 'utf8');
-            // Simple regex to extract FIXPT value
             const fixptMatch = xmlContent.match(/<FIXPT>([^<]+)<\/FIXPT>/);
             if (fixptMatch && fixptMatch[1] === 'X') {
               obj.fixpt = 'X';
             } else {
-              // No FIXPT tag means FIXPT=false (blank)
               obj.fixpt = '';
             }
+            if (objType === 'PROG') {
+              const subcMatch = xmlContent.match(/<SUBC>([^<]+)<\/SUBC>/);
+              obj.subc = subcMatch ? subcMatch[1] : '';
+
+              // INCLUDE programs: stash for parent auto-detection instead of pushing directly
+              if (obj.subc === 'I') {
+                progIncludeMap.set(objName, { filePath, source });
+                continue; // skip objects.push — handled after auto-detection below
+              }
+            }
           }
         }
 
@@ -330,12 +361,102 @@ module.exports = {
       }
     }
 
+    // Helper: read SUBC from a .prog.xml file
+    function readProgSubc(xmlPath) {
+      if (!fs.existsSync(xmlPath)) return '';
+      const xml = fs.readFileSync(xmlPath, 'utf8');
+      const m = xml.match(/<SUBC>([^<]+)<\/SUBC>/);
+      return m ? m[1] : '';
+    }
+
+    // Helper: read FIXPT from a .prog.xml file
+    function readProgFixpt(xmlPath) {
+      if (!fs.existsSync(xmlPath)) return '';
+      const xml = fs.readFileSync(xmlPath, 'utf8');
+      const m = xml.match(/<FIXPT>([^<]+)<\/FIXPT>/);
+      return (m && m[1] === 'X') ? 'X' : '';
+    }
+
+    // Auto-detect parent program for INCLUDE files
+    // Scan the same directory for .prog.abap files that contain INCLUDE <name>.
+    // Assemble the parent source with the INCLUDE source substituted in-place.
+    for (const [includeName, includeData] of progIncludeMap) {
+      const includeDir = pathModule.dirname(includeData.filePath);
+      let parentFound = false;
+
+      let dirEntries;
+      try {
+        dirEntries = fs.readdirSync(includeDir);
+      } catch (e) {
+        dirEntries = [];
+      }
+
+      for (const entry of dirEntries) {
+        if (!entry.toLowerCase().endsWith('.prog.abap')) continue;
+        const candidatePath = pathModule.join(includeDir, entry);
+        if (candidatePath === includeData.filePath) continue; // skip itself
+
+        // Only consider executable/non-include programs as parents
+        const candidateName = entry.split('.')[0].toUpperCase();
+        const candidateXml = pathModule.join(includeDir, `${candidateName.toLowerCase()}.prog.xml`);
+        const candidateSubc = readProgSubc(candidateXml);
+        if (candidateSubc === 'I') continue; // another INCLUDE — skip
+
+        const parentSource = fs.readFileSync(candidatePath, 'utf8');
+        const parentLines = parentSource.split('\n');
+
+        // Find `INCLUDE <includeName>.` line (case-insensitive)
+        const includeRegex = new RegExp(`^\\s*INCLUDE\\s+${includeName}\\s*\\.`, 'i');
+        const includeLineIdx = parentLines.findIndex(l => includeRegex.test(l));
+        if (includeLineIdx === -1) continue;
+
+        // Found parent — assemble: replace INCLUDE statement with include's source lines
+        const includeLines = includeData.source.split('\n');
+        const assembled = [
+          ...parentLines.slice(0, includeLineIdx),
+          ...includeLines,
+          ...parentLines.slice(includeLineIdx + 1)
+        ];
+        const assembledSource = assembled.join('\n');
+
+        if (!jsonOutput) {
+          console.log(`  Auto-detected parent: ${entry} (contains INCLUDE ${includeName}.)`);
+        }
+
+        objects.push({
+          type: 'PROG',
+          name: candidateName,
+          source: assembledSource,
+          subc: candidateSubc || '1',
+          fixpt: readProgFixpt(candidateXml),
+          // offset into assembled source where include lines start (1-based)
+          include_offset: includeLineIdx + 1,
+          include_line_count: includeLines.length,
+          // carry include name for error line mapping
+          include_name: includeName
+        });
+
+        parentFound = true;
+        break; // use first matching parent
+      }
+
+      if (!parentFound) {
+        if (!jsonOutput) {
+          console.error(`  Warning: No parent program found for INCLUDE ${includeName} — cannot syntax-check standalone`);
+        }
+      }
+    }
+
     if (objects.length === 0) {
       console.error('  No valid files to check');
       process.exit(1);
     }
     const data = {
-      objects: objects,
+      objects: objects.map(o => {
+        // Strip client-side INCLUDE tracking fields before sending to ABAP
+        const { include_offset, include_line_count, include_name, ...abapObj } = o; // eslint-disable-line no-unused-vars
+        return abapObj;
+      }),
       uccheck: cloudMode ? '5' : 'X'
     };
 
@@ -365,26 +486,56 @@ module.exports = {
         const fugrFmLabel = (objType === 'FUGR' && sentObj.fugr_include_name)
           ? ` (${sentObj.fugr_include_name})` : '';
 
+        // For INCLUDE-backed checks: determine display label and line remapping
+        const includeLabel = sentObj.include_name
+          ? ` (checking via parent ${objName})` : '';
+
         if (objSuccess) {
-          console.log(`✅ ${objType} ${objName}${fugrFmLabel} - Syntax check passed`);
+          if (sentObj.include_name) {
+            console.log(`✅ PROG ${sentObj.include_name} - Syntax check passed${includeLabel}`);
+          } else {
+            console.log(`✅ ${objType} ${objName}${fugrFmLabel} - Syntax check passed`);
+          }
           if (warnings.length > 0) {
             console.log(`   (${warnings.length} warning(s))`);
           }
         } else {
-          console.log(`❌ ${objType} ${objName}${fugrFmLabel} - Syntax check failed (${errorCount} error(s))`);
+          if (sentObj.include_name) {
+            console.log(`❌ PROG ${sentObj.include_name} - Syntax check failed (${errorCount} error(s))${includeLabel}`);
+          } else {
+            console.log(`❌ ${objType} ${objName}${fugrFmLabel} - Syntax check failed (${errorCount} error(s))`);
+          }
           console.log('');
           console.log('Errors:');
           console.log('─'.repeat(60));
 
           for (const err of errors) {
-            const line = err.LINE || err.line || '?';
+            let line = err.LINE || err.line || '?';
             const column = err.COLUMN || err.column || '';
             const text = err.TEXT || err.text || 'Unknown error';
             const methodName = err.METHOD_NAME || err.method_name || '';
             const include = err.INCLUDE || err.include || '';
 
+            // Remap line numbers for INCLUDE-backed checks
+            let remappedFile = null;
+            if (sentObj.include_name && typeof line === 'number') {
+              const offset = sentObj.include_offset || 0;
+              const count = sentObj.include_line_count || 0;
+              if (line >= offset && line < offset + count) {
+                // Error is inside the INCLUDE — remap to include-relative line
+                line = line - offset + 1;
+                remappedFile = `${sentObj.include_name.toLowerCase()}.prog.abap`;
+              } else {
+                // Error is in the parent program context (e.g. header line)
+                remappedFile = `${objName.toLowerCase()}.prog.abap (parent)`;
+              }
+            }
+
             // Display which file/include the error is in
-            if (include) {
+            if (remappedFile) {
+              // INCLUDE-backed check: show the actual source file the error maps to
+              console.log(`  In: ${remappedFile}`);
+            } else if (include) {
               // For FUGR: include = lowercase FM name → display as '<group>.fugr.<fm_name>.abap'
               if (objType === 'FUGR') {
                 const fugrFile = `${objName.toLowerCase()}.fugr.${include}.abap`;

package/src/commands/tree.js

@@ -148,6 +148,28 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent tree --package <package> [--depth <n>] [--include-types] [--json]
+
+Description:
+  Display the package hierarchy tree from the ABAP system.
+
+Parameters:
+  --package <package>  Root package to display (required). Enclose $-packages in quotes.
+  --depth <n>          Maximum depth to traverse (default: unlimited).
+  --include-types      Show object type counts per package.
+  --json               Output as JSON.
+
+Examples:
+  abapgit-agent tree --package ZMY_PACKAGE
+  abapgit-agent tree --package '$MY_LOCAL_PKG'
+  abapgit-agent tree --package ZMY_PACKAGE --depth 2 --include-types
+`);
+      return;
+    }
+
     const packageArgIndex = args.indexOf('--package');
     if (packageArgIndex === -1) {
       console.error('Error: --package parameter required');

package/src/commands/unit.js

@@ -232,6 +232,29 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent unit --files <file1>,<file2>,... [--coverage] [--junit-output <file>] [--json]
+
+Description:
+  Run AUnit tests for ABAP test class files (.testclasses.abap).
+  Objects must be already active in the ABAP system (run pull first).
+
+Parameters:
+  --files <file1,...>     Comma-separated .testclasses.abap files (required).
+  --coverage              Include code coverage data in output.
+  --junit-output <file>   Write results as JUnit XML to this file.
+  --json                  Output as JSON.
+
+Examples:
+  abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap
+  abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap --coverage
+  abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap --junit-output reports/unit.xml
+`);
+      return;
+    }
+
     const jsonOutput = args.includes('--json');
     const verbose = args.includes('--verbose');
     const filesArgIndex = args.indexOf('--files');

package/src/commands/upgrade.js

@@ -14,6 +14,34 @@ module.exports = {
   async execute(args, context) {
     const { versionCheck, loadConfig, isAbapIntegrationEnabled } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent upgrade [--abap-only] [--cli-only] [--version <v>] [--check] [--yes]
+
+Description:
+  Upgrade the abapgit-agent CLI (npm package) and/or the ABAP backend to the latest
+  or a specific version.
+
+Parameters:
+  --abap-only        Upgrade only the ABAP backend (skip CLI npm upgrade).
+  --cli-only         Upgrade only the CLI npm package (skip ABAP backend).
+  --version <v>      Upgrade to a specific version (e.g. 1.15.0).
+  --check            Check for available upgrades without installing.
+  --transport <T>    Transport request for ABAP backend upgrade.
+  --yes, -y          Skip confirmation prompt.
+  --dry-run          Show what would be done without making changes.
+
+Examples:
+  abapgit-agent upgrade
+  abapgit-agent upgrade --check
+  abapgit-agent upgrade --cli-only
+  abapgit-agent upgrade --abap-only --transport DEVK900001
+  abapgit-agent upgrade --version 1.15.0
+`);
+      return;
+    }
+
     // Parse flags
     const flags = this.parseFlags(args);
 

package/src/commands/view.js

@@ -193,6 +193,35 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent view --objects <obj1>,<obj2>,... [--type <type>] [--full] [--lines] [--json]
+  abapgit-agent view --objects <FUGR> --type FUGR [--full] [--fm <name>] [--lines]
+
+Description:
+  View ABAP object definitions from the ABAP system.
+
+Parameters:
+  --objects <obj1,...>  Comma-separated object names (required).
+  --type <type>         Object type: CLAS, INTF, PROG, TABL, STRU, DTEL, TTYP, DOMA,
+                        DDLS, DCLS, MSAG, FUGR (auto-detected from TADIR if omitted).
+  --full                Show full source including all method implementations.
+  --lines               Show dual line numbers (G = global for debug set, [N] = include-local).
+  --fm <name>           With --full: show only the specified function module (FUGR only).
+  --json                Output as JSON.
+
+Examples:
+  abapgit-agent view --objects ZCL_MY_CLASS
+  abapgit-agent view --objects ZCL_MY_CLASS --full
+  abapgit-agent view --objects ZCL_MY_CLASS --full --lines
+  abapgit-agent view --objects ZMY_TABLE --type TABL
+  abapgit-agent view --objects SUSR --type FUGR --full --fm AUTHORITY_CHECK --lines
+  abapgit-agent view --objects ZCL_FOO,ZIF_BAR
+`);
+      return;
+    }
+
     const objectsArgIndex = args.indexOf('--objects');
     if (objectsArgIndex === -1 || objectsArgIndex + 1 >= args.length) {
       console.error('Error: --objects parameter required');

package/src/commands/where.js

@@ -11,6 +11,30 @@ module.exports = {
   async execute(args, context) {
     const { loadConfig, AbapHttp } = context;
 
+    if (args.includes('--help') || args.includes('-h')) {
+      console.log(`
+Usage:
+  abapgit-agent where --objects <obj1>,<obj2>,... [--type <type>] [--limit <n>] [--offset <n>] [--json]
+
+Description:
+  Find where-used list for ABAP objects (classes, interfaces, programs, etc.).
+
+Parameters:
+  --objects <obj1,...>  Comma-separated object names (required).
+  --type <type>         Object type (e.g. CLAS, INTF — auto-detected if omitted).
+  --limit <n>           Maximum number of results (default: 50).
+  --offset <n>          Skip first N results (for pagination).
+  --json                Output as JSON.
+
+Examples:
+  abapgit-agent where --objects ZCL_MY_CLASS
+  abapgit-agent where --objects ZIF_MY_INTERFACE
+  abapgit-agent where --objects ZCL_MY_CLASS --limit 20
+  abapgit-agent where --objects ZCL_MY_CLASS --offset 50 --limit 20
+`);
+      return;
+    }
+
     const objectsArgIndex = args.indexOf('--objects');
     if (objectsArgIndex === -1 || objectsArgIndex + 1 >= args.length) {
       console.error('Error: --objects parameter required');

package/src/config.js

@@ -123,6 +123,7 @@ function getSafeguards() {
       requireFilesForPull: projectConfig.safeguards.requireFilesForPull === true,
       disablePull: projectConfig.safeguards.disablePull === true,
       disableRun: projectConfig.safeguards.disableRun === true,
+      disableImport: projectConfig.safeguards.disableImport === true,
       disableProbeClasses: projectConfig.safeguards.disableProbeClasses === true,
       reason: projectConfig.safeguards.reason || null
     };
@@ -133,6 +134,7 @@ function getSafeguards() {
     requireFilesForPull: false,
     disablePull: false,
     disableRun: false,
+    disableImport: false,
     disableProbeClasses: false,
     reason: null
   };

package/src/utils/abap-reference.js

@@ -531,8 +531,8 @@ async function getTopic(topic) {
           return {
             topic,
             file: guidelineFile,
-            content: content.slice(0, 15000),
-            truncated: content.length > 15000,
+            content: content.slice(0, 20000),
+            truncated: content.length > 20000,
             totalLength: content.length,
             source: 'guidelines'
           };
@@ -616,8 +616,8 @@ async function getTopic(topic) {
         return {
           topic,
           file: exactMatch,
-          content: content.slice(0, 15000),
-          truncated: content.length > 15000,
+          content: content.slice(0, 20000),
+          truncated: content.length > 20000,
           totalLength: content.length,
           source: 'built-in guidelines'
         };
@@ -630,8 +630,8 @@ async function getTopic(topic) {
         return {
           topic,
           file: partialMatches[0],
-          content: content.slice(0, 15000),
-          truncated: content.length > 15000,
+          content: content.slice(0, 20000),
+          truncated: content.length > 20000,
           totalLength: content.length,
           source: 'built-in guidelines'
         };
@@ -814,11 +814,10 @@ function displayTopic(result) {
   console.log('  ' + '─'.repeat(60));
   console.log('');
 
-  // Display up to 300 lines (covers full guideline files without truncation)
-  const lines = result.content.split('\n').slice(0, 300);
+  // Display full content (char limit already applied when reading)
+  const lines = result.content.split('\n');
   lines.forEach(line => {
-    const trimmed = line.slice(0, 100);
-    console.log(`  ${trimmed}`);
+    console.log(`  ${line}`);
   });
 
   if (result.truncated) {