abapgit-agent 1.10.0 → 1.11.0

package/abap/CLAUDE.md

@@ -308,32 +308,26 @@ abapgit-agent debug list    # confirm it was registered
 
 **Step 2 — attach and trigger**
 
-Two modes depending on context:
+Best practice: individual sequential calls. Once the daemon is running and
+the session is saved to the state file, each `vars/stack/step` command is a
+plain standalone call — no `--session` flag needed.
 
-*Interactive (human in a terminal):*
 ```bash
-# Terminal 1 — attach (blocks waiting for breakpoint, opens REPL on hit)
-abapgit-agent debug attach
-
-# Terminal 2 — trigger (any command that calls the backend)
-abapgit-agent unit --files src/zcl_my_class.clas.testclasses.abap
-abapgit-agent inspect --files src/zcl_my_class.clas.abap
-```
-
-*Scripted (AI / automation) — best practice: individual sequential calls:*
-
-Once the daemon is running and the session is saved to the state file, each
-`vars/stack/step` command is a plain standalone call — no bash script needed.
-
-```bash
-# Step 1: start attach listener in background (spawns a daemon, saves session to state file)
+# Start attach listener in background (spawns a daemon, saves session to state file)
 abapgit-agent debug attach --json > /tmp/attach.json 2>&1 &
-sleep 2
 
-# Step 2: trigger in background — MUST stay alive for the whole session
+# Rule 1: wait for "Listener active" in the output, THEN fire the trigger.
+# attach --json prints "Listener active" to stderr (captured in attach.json) the
+# moment the long-poll POST is about to be sent to ADT.  Waiting for this marker
+# is reliable under any system load; a blind sleep may fire the trigger before
+# ADT has a registered listener, causing the breakpoint hit to be missed.
+until grep -q "Listener active" /tmp/attach.json 2>/dev/null; do sleep 0.3; done
+sleep 1   # brief extra window for the POST to reach ADT
+
+# Trigger in background — MUST stay alive for the whole session
 abapgit-agent unit --files src/zcl_my_class.clas.testclasses.abap > /tmp/trigger.json 2>&1 &
 
-# Step 3: poll until breakpoint fires and session JSON appears in attach output
+# Poll until breakpoint fires and session JSON appears in attach output
 SESSION=""
 for i in $(seq 1 30); do
   sleep 0.5
@@ -341,40 +335,29 @@ for i in $(seq 1 30); do
   [ -n "$SESSION" ] && break
 done
 
-# Step 4: inspect and step — each is an individual call, no --session needed
+# Inspect and step — each is an individual call, no --session needed
 abapgit-agent debug stack --json
 abapgit-agent debug vars  --json
 abapgit-agent debug vars  --expand LS_OBJECT --json
 abapgit-agent debug step  --type over --json
 abapgit-agent debug vars  --json
 
-# Step 5: ALWAYS release the ABAP work process before finishing
+# ALWAYS release the ABAP work process before finishing
 abapgit-agent debug step --type continue --json
 
-# Step 6: check trigger result
+# Check trigger result
 cat /tmp/trigger.json
 rm -f /tmp/attach.json /tmp/trigger.json
 ```
 
 > **Four rules for scripted mode:**
-> 1. `sleep 2` after starting attach — the listener must register on the server before the trigger fires
+> 1. Wait for `"Listener active"` in the attach output before firing the trigger — this message is printed to stderr (captured in `attach.json`) the moment the listener POST is about to reach ADT. A blind `sleep` is not reliable under system load.
 > 2. Keep the trigger process alive in the background for the entire session — if it exits, the ABAP work process is released and the session ends
 > 3. Always finish with `step --type continue` — this releases the frozen work process so the trigger can complete normally
 > 4. **Never pass `--session` to `step/vars/stack`** — it bypasses the daemon IPC and causes `noSessionAttached`. Omit it and let commands auto-load from the saved state file.
 
 **Step 3 — step through and inspect**
 
-*Interactive REPL commands (after `attach` without `--json`):*
-```
-  debug> v          — show all variables
-  debug> x LT_DATA  — expand a table or structure
-  debug> n          — step over
-  debug> s          — step into
-  debug> bt         — call stack
-  debug> q          — detach (program continues); kill — hard abort
-```
-
-*Scripted commands (after `attach --json`) — omit `--session`, commands auto-load from state file:*
 ```bash
 abapgit-agent debug vars   --json                        # all variables
 abapgit-agent debug vars   --name LV_RESULT --json       # one variable
@@ -396,6 +379,24 @@ abapgit-agent debug delete --all
 
 This project's workflow mode is configured in `.abapGitAgent` under `workflow.mode`.
 
+### Project-Level Config (`.abapgit-agent.json`)
+
+Checked into the repository — applies to all developers. **Read this file at the start of every session.**
+
+| Setting | Values | Default | Effect |
+|---------|--------|---------|--------|
+| `safeguards.requireFilesForPull` | `true`/`false` | `false` | Requires `--files` on every pull |
+| `safeguards.disablePull` | `true`/`false` | `false` | Disables pull entirely (CI/CD-only projects) |
+| `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 |
+| `transports.allowCreate` | `true`/`false` | `true` | When `false`, `transport create` is blocked |
+| `transports.allowRelease` | `true`/`false` | `true` | When `false`, `transport release` is blocked |
+
+CLI `--conflict-mode` always overrides the project config for a single run.
+
+See **AI Tool Guidelines** below for how to react to each setting.
+
 ### Workflow Modes
 
 | Mode | Branch Strategy | Rebase Before Pull | Create PR |
@@ -571,6 +572,37 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 3. ✓ `git pull origin <default>` before push
 4. ✗ Don't create feature branches
 
+**Read `.abapgit-agent.json` to determine project safeguards and conflict detection:**
+
+**When `safeguards.requireFilesForPull = true`:**
+1. ✓ Always include `--files` in every `pull` command
+2. ✓ Never run `abapgit-agent pull` without `--files`
+3. ✗ Don't suggest or run a full pull without specifying files
+
+**When `safeguards.requireFilesForPull = false` or not set:**
+1. ✓ `--files` is optional — use it for speed, omit for full pull
+
+**When `safeguards.disablePull = true`:**
+1. ✗ Do not run `abapgit-agent pull` at all
+2. ✓ Inform the user that pull is disabled for this project (CI/CD only)
+
+**When `conflictDetection.mode = "ignore"` or not set:**
+1. ✓ Run `pull` normally — no conflict flags needed
+2. ✗ Don't add `--conflict-mode` unless user explicitly asks
+
+**When `conflictDetection.mode = "abort"`:**
+1. ✓ Conflict detection is active — pull aborts if ABAP system was edited since last pull
+2. ✓ If pull is aborted with conflict error, inform user and suggest `--conflict-mode ignore` to override for that run
+3. ✗ Don't silently add `--conflict-mode ignore` — always tell the user about the conflict
+
+**When `transports.allowCreate = false`:**
+1. ✗ Do not run `abapgit-agent transport create`
+2. ✓ Inform the user that transport creation is disabled for this project
+
+**When `transports.allowRelease = false`:**
+1. ✗ Do not run `abapgit-agent transport release`
+2. ✓ Inform the user that transport release is disabled for this project
+
 ---
 
 ## Development Workflow (Detailed)
@@ -600,6 +632,7 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
        │
        ▼
 6. Activate → abapgit-agent pull --files src/file.clas.abap
+       │         (behaviour depends on .abapgit-agent.json — see AI Tool Guidelines)
        │
        ▼
 7. Verify → Check pull output
@@ -791,6 +824,9 @@ abapgit-agent syntax --files src/zcl_class1.clas.abap,src/zif_intf1.intf.abap,sr
 # 2. Pull/activate AFTER pushing to git
 abapgit-agent pull --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap
 
+# Override conflict detection for a single pull (e.g. deliberate branch switch)
+abapgit-agent pull --files src/zcl_class1.clas.abap --conflict-mode ignore
+
 # 3. Inspect AFTER pull (for errors or unsupported types)
 abapgit-agent inspect --files src/zcl_class1.clas.abap
 

package/bin/abapgit-agent

@@ -24,7 +24,7 @@ const gitUtils = require('../src/utils/git-utils');
 const versionCheck = require('../src/utils/version-check');
 const validators = require('../src/utils/validators');
 const { AbapHttp } = require('../src/utils/abap-http');
-const { loadConfig, getTransport, isAbapIntegrationEnabled, getSafeguards } = require('../src/config');
+const { loadConfig, getTransport, isAbapIntegrationEnabled, getSafeguards, getConflictSettings, getTransportSettings } = require('../src/config');
 
 // Get terminal width for responsive table
 const getTermWidth = () => process.stdout.columns || 80;
@@ -55,7 +55,8 @@ async function main() {
     ref: require('../src/commands/ref'),
     init: require('../src/commands/init'),
     pull: require('../src/commands/pull'),
-    upgrade: require('../src/commands/upgrade')
+    upgrade: require('../src/commands/upgrade'),
+    transport: require('../src/commands/transport')
   };
 
   // Check if this is a modular command
@@ -102,7 +103,9 @@ To enable integration:
       loadConfig,
       AbapHttp,
       getTransport,
-      getSafeguards
+      getSafeguards,
+      getConflictSettings,
+      getTransportSettings
     };
 
     // Execute command
@@ -121,4 +124,11 @@ To enable integration:
   process.exit(1);
 }
 
-main();
+main().catch((err) => {
+  // Known CLI errors (e.g. pull conflict) already printed their own output — skip re-printing.
+  // For all other unexpected errors, print the message without the stack trace.
+  if (!err._isPullError && !err._isTransportError) {
+    console.error(err.message || err);
+  }
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [
@@ -42,6 +42,8 @@
     "test:cmd:upgrade": "node tests/run-all.js --cmd --command=upgrade",
     "test:lifecycle": "node tests/run-all.js --lifecycle",
     "test:pull": "node tests/run-all.js --pull",
+    "test:full-pull": "node tests/run-all.js --full-pull",
+    "test:conflict": "node tests/run-all.js --conflict",
     "pull": "node bin/abapgit-agent",
     "release": "node scripts/release.js",
     "unrelease": "node scripts/unrelease.js"

package/src/commands/debug.js

@@ -583,7 +583,7 @@ async function cmdAttach(args, config, adt) {
     let firstPoll = true;
 
     for (let i = 0; i < (takenOver ? MAX_TAKEOVER_POLLS : MAX_POLLS); i++) {
-      if (firstPoll && !jsonOutput) {
+      if (firstPoll) {
         process.stderr.write('  Listener active — trigger your ABAP program now.\n');
         firstPoll = false;
       }
@@ -806,7 +806,7 @@ async function cmdStep(args, config, adt) {
       process.exit(1);
     }
     if (!resp.ok) {
-      console.error(`\n  Error: ${resp.error}${resp.statusCode ? ` (HTTP ${resp.statusCode})` : ''}\n`);
+      console.error(`\n  Error: ${resp.error}${resp.statusCode ? ` (HTTP ${resp.statusCode})` : ''}${resp.body ? '\n  Body: ' + resp.body.substring(0, 400) : ''}\n`);
       process.exit(1);
     }
     // continued+finished (or empty position) means the program ran to completion
@@ -1074,7 +1074,7 @@ async function cmdStack(args, config, adt) {
       process.exit(1);
     }
     if (!resp.ok) {
-      console.error(`\n  Error: ${resp.error}${resp.statusCode ? ` (HTTP ${resp.statusCode})` : ''}\n`);
+      console.error(`\n  Error: ${resp.error}${resp.statusCode ? ` (HTTP ${resp.statusCode})` : ''}${resp.body ? '\n  Body: ' + resp.body.substring(0, 400) : ''}\n`);
       process.exit(1);
     }
     const frames = resp.frames;

package/src/commands/pull.js

@@ -9,7 +9,7 @@ module.exports = {
   requiresVersionCheck: true,
 
   async execute(args, context) {
-    const { loadConfig, AbapHttp, gitUtils, getTransport, getSafeguards } = context;
+    const { loadConfig, AbapHttp, gitUtils, getTransport, getSafeguards, getConflictSettings, getTransportSettings } = context;
 
     // Check project-level safeguards
     const safeguards = getSafeguards();
@@ -29,14 +29,16 @@ module.exports = {
     const branchArgIndex = args.indexOf('--branch');
     const filesArgIndex = args.indexOf('--files');
     const transportArgIndex = args.indexOf('--transport');
+    const conflictModeArgIndex = args.indexOf('--conflict-mode');
     const jsonOutput = args.includes('--json');
 
     // Auto-detect git remote URL if not provided
     let gitUrl = urlArgIndex !== -1 ? args[urlArgIndex + 1] : null;
     let branch = branchArgIndex !== -1 ? args[branchArgIndex + 1] : gitUtils.getBranch();
     let files = null;
+    let conflictMode = conflictModeArgIndex !== -1 ? args[conflictModeArgIndex + 1] : getConflictSettings().mode;
 
-    // Transport: CLI arg takes priority, then config/environment, then null
+    // Transport: CLI arg takes priority, then config/environment, then selector
     let transportRequest = null;
     if (transportArgIndex !== -1 && transportArgIndex + 1 < args.length) {
       // Explicit --transport argument
@@ -46,8 +48,39 @@ module.exports = {
       transportRequest = getTransport();
     }
 
+    // Auto-detect URL early (needed for transport_required check)
+    if (!gitUrl) {
+      gitUrl = gitUtils.getRemoteUrl();
+      if (!gitUrl) {
+        console.error('Error: Not in a git repository or no remote configured.');
+        console.error('Either run from a git repo, or specify --url <git-url>');
+        process.exit(1);
+      }
+      if (!jsonOutput) {
+        console.log(`📌 Auto-detected git remote: ${gitUrl}`);
+      }
+    }
+
     if (filesArgIndex !== -1 && filesArgIndex + 1 < args.length) {
       files = args[filesArgIndex + 1].split(',').map(f => f.trim());
+
+      // Validate that every file has a recognised ABAP source extension
+      // (.abap or .asddls) — XML metadata files must NOT be passed here
+      const ABAP_SOURCE_EXTS = new Set(['abap', 'asddls']);
+      const nonSourceFiles = files.filter(f => {
+        const base = f.split('/').pop(); // strip directory
+        const parts = base.split('.');
+        const ext = parts[parts.length - 1].toLowerCase();
+        return parts.length < 3 || !ABAP_SOURCE_EXTS.has(ext);
+      });
+      if (nonSourceFiles.length > 0) {
+        console.error('❌ Error: --files only accepts ABAP source files (.abap, .asddls).');
+        console.error('   The following file(s) are not ABAP source files:');
+        nonSourceFiles.forEach(f => console.error(`     ${f}`));
+        console.error('   Tip: pass the source file, not the XML metadata file.');
+        console.error('   Example: --files src/zcl_my_class.clas.abap');
+        process.exit(1);
+      }
     }
 
     // SAFEGUARD 2: Check if files are required but not provided
@@ -62,22 +95,59 @@ module.exports = {
       process.exit(1);
     }
 
-    if (!gitUrl) {
-      gitUrl = gitUtils.getRemoteUrl();
-      if (!gitUrl) {
-        console.error('Error: Not in a git repository or no remote configured.');
-        console.error('Either run from a git repo, or specify --url <git-url>');
-        process.exit(1);
+    // Auto-select transport when none configured and not in JSON mode
+    if (!transportRequest && !jsonOutput) {
+      const { selectTransport, isNonInteractive, _getTransportHookConfig } = require('../utils/transport-selector');
+
+      // Check if this package requires a transport before showing the interactive
+      // picker. Skip the status round-trip in non-interactive mode — selectTransport
+      // already returns null there without prompting, so the extra HTTP call is wasted.
+      let transportRequired = true; // Safe default: assume transport needed
+      if (!isNonInteractive()) {
+        try {
+          const config = loadConfig();
+          const http = new AbapHttp(config);
+          const csrfToken = await http.fetchCsrfToken();
+          const statusResult = await http.post('/sap/bc/z_abapgit_agent/status', { url: gitUrl }, { csrfToken });
+          if (statusResult.transport_required === false || statusResult.transport_required === 'false') {
+            transportRequired = false;
+          }
+        } catch (e) {
+          // Status check failed — proceed with selector as safe default
+        }
       }
-      if (!jsonOutput) {
-        console.log(`📌 Auto-detected git remote: ${gitUrl}`);
+
+      if (transportRequired) {
+        const config = loadConfig();
+        const http = new AbapHttp(config);
+        transportRequest = await selectTransport(config, http, loadConfig, AbapHttp, getTransportSettings);
+
+        // If a hook was configured but returned no transport, handle based on context
+        if (transportRequest === null) {
+          const hookConfig = _getTransportHookConfig();
+          if (hookConfig && hookConfig.hook) {
+            if (isNonInteractive()) {
+              // Non-interactive (AI/CI): fail — a configured hook must return a transport
+              console.error('❌ Error: transport hook returned no transport request.');
+              console.error(`   Hook: ${hookConfig.hook}`);
+              if (hookConfig.description) console.error(`   ${hookConfig.description}`);
+              process.exit(1);
+            } else {
+              // Interactive (TTY): warn and fall through to the picker
+              process.stderr.write(`⚠️  Transport hook returned no transport request (${hookConfig.hook}).\n`);
+              process.stderr.write('   Please select one manually:\n');
+              const { interactivePicker } = require('../utils/transport-selector');
+              transportRequest = await interactivePicker(http);
+            }
+          }
+        }
       }
     }
 
-    await this.pull(gitUrl, branch, files, transportRequest, loadConfig, AbapHttp, jsonOutput);
+    await this.pull(gitUrl, branch, files, transportRequest, loadConfig, AbapHttp, jsonOutput, undefined, conflictMode);
   },
 
-  async pull(gitUrl, branch = 'main', files = null, transportRequest = null, loadConfig, AbapHttp, jsonOutput = false, gitCredentials = undefined) {
+  async pull(gitUrl, branch = 'main', files = null, transportRequest = null, loadConfig, AbapHttp, jsonOutput = false, gitCredentials = undefined, conflictMode = 'abort') {
     const TERM_WIDTH = process.stdout.columns || 80;
 
     if (!jsonOutput) {
@@ -107,6 +177,7 @@ module.exports = {
       const data = {
         url: gitUrl,
         branch: branch,
+        conflict_mode: conflictMode,
         ...(resolvedCredentials ? { username: resolvedCredentials.username, password: resolvedCredentials.password } : {})
       };
 
@@ -140,12 +211,23 @@ module.exports = {
       const jobId = result.JOB_ID || result.job_id;
       const message = result.MESSAGE || result.message;
       const errorDetail = result.ERROR_DETAIL || result.error_detail;
-      const transportRequestUsed = result.TRANSPORT_REQUEST || result.transport_request;
       const activatedCount = result.ACTIVATED_COUNT || result.activated_count || 0;
       const failedCount = result.FAILED_COUNT || result.failed_count || 0;
       const logMessages = result.LOG_MESSAGES || result.log_messages || [];
       const activatedObjects = result.ACTIVATED_OBJECTS || result.activated_objects || [];
       const failedObjects = result.FAILED_OBJECTS || result.failed_objects || [];
+      const conflictReport = result.CONFLICT_REPORT || result.conflict_report || '';
+      const conflictCount = result.CONFLICT_COUNT || result.conflict_count || 0;
+
+      // --- Conflict report (pull was aborted) ---
+      if (conflictCount > 0 && conflictReport) {
+        console.error(`⚠️  Pull aborted — ${conflictCount} conflict(s) detected\n`);
+        console.error('─'.repeat(TERM_WIDTH));
+        console.error(conflictReport.replace(/\\n/g, '\n'));
+        const err = new Error(message || `Pull aborted — ${conflictCount} conflict(s) detected`);
+        err._isPullError = true;
+        throw err;
+      }
 
       // Icon mapping for message types
       const getIcon = (type) => {

package/src/commands/status.js

@@ -32,7 +32,9 @@ module.exports = {
             console.log('   Repository: ✅ Created');
             const pkg = result.package || result.PACKAGE || 'N/A';
             const key = result.key || result.KEY || result.REPO_KEY || result.repo_key || 'N/A';
+            const transportRequired = result.transport_required === true || result.transport_required === 'true';
             console.log(`      Package: ${pkg}`);
+            console.log(`      Transport required: ${transportRequired ? 'Yes' : 'No'}`);
             console.log(`      URL: ${repoUrl}`);
             console.log(`      Key: ${key}`);
           } else {