abapgit-agent 1.11.4 → 1.12.1

package/abap/CLAUDE.md

@@ -225,19 +225,50 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 
 ---
 
-### 9. Troubleshooting ABAP Issues
+### 9. Never Run `run` Command Proactively
+
+**Never call `abapgit-agent run` unless the user explicitly asks.** A class implementing `IF_OO_ADT_CLASSRUN` can modify data, send emails, or trigger RFCs — running it automatically is unsafe.
+
+After activating a class, stop and tell the user: `"Class is activated. Run with: abapgit-agent run --class ZCL_MY_CLASS"`
+
+---
+
+### 10. Probe Classes — Use `scratchWorkspace` When Required
+
+By default, probe/throwaway classes may be created in the current project. When `disableProbeClasses: true` is set in `.abapgit-agent.json`, they must go to `scratchWorkspace` instead. If `scratchWorkspace` is also not configured, refuse and guide the user to set it up.
+
+→ See `guidelines/run-probe-classes.md` for naming conventions, full workflow, and refusal guidance
+
+---
+
+### 11. Troubleshooting ABAP Issues
 
 | Symptom | Tool | When |
 |---|---|---|
 | HTTP 500 / runtime crash (ST22) | `dump` | Error already occurred |
 | Wrong output, no crash | `debug` | Need to trace logic |
 
-Quick start:
+→ See `guidelines/debug-dump.md` for dump analysis workflow
+
+**Critical rules for `debug` sessions:**
+
+1. **Always use `--json`** for all debug commands (`attach`, `vars`, `stack`, `step`) — human output is not machine-parseable
+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
+5. **Always finish with `step --type continue --json`** — releases the frozen ABAP work process
+
+Minimal correct sequence:
 ```bash
-abapgit-agent dump --date TODAY --detail 1    # inspect last crash
-abapgit-agent debug set --objects ZCL_FOO:42  # set breakpoint then attach
+abapgit-agent debug set --objects ZCL_FOO:42        # 1. set breakpoint
+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
+# poll for session, then inspect
+abapgit-agent debug vars --json
+abapgit-agent debug step --type continue --json     # 4. release
 ```
-→ See `guidelines/debug-dump.md` for dump analysis workflow
+
 → See `guidelines/debug-session.md` for full debug session guide, breakpoint tips, and pull flow architecture
 
 ---
@@ -326,6 +357,13 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 1. ✗ Do not run `abapgit-agent pull` at all
 2. ✓ Inform the user that pull is disabled for this project (CI/CD only)
 
+**When `safeguards.disableRun = true`:**
+1. ✗ Do not run `abapgit-agent run` at all
+2. ✓ Inform the user that run is disabled for this project
+
+**When `safeguards.disableProbeClasses = true`:**
+1. ✗ Do not create probe classes in the current project — see Rule 10 and `guidelines/run-command.md`
+
 **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
@@ -339,6 +377,12 @@ abapgit-agent pull --files src/zcl_auth_handler.clas.abap
 1. ✗ Do not run `abapgit-agent transport create`
 2. ✓ Inform the user that transport creation is disabled for this project
 
+**When pull result contains `missing_abapgit_xml: true` (JSON mode) or warning about `.abapgit.xml`:**
+1. ✓ Inform the user that `.abapgit.xml` is missing from the repository root
+2. ✓ Suggest running `abapgit-agent init --package <PACKAGE>` to create it
+3. ✓ If `ACTIVATED_COUNT=0` with an empty log, suspect this as the cause
+4. ✗ Do not retry the pull — fix the missing file first
+
 **When `transports.allowRelease = false`:**
 1. ✗ Do not run `abapgit-agent transport release`
 2. ✓ Inform the user that transport release is disabled for this project
@@ -384,6 +428,7 @@ Detailed guidelines are available in the `guidelines/` folder:
 | `guidelines/common-errors.md` | Common ABAP Errors - Quick Fixes |
 | `guidelines/debug-session.md` | Debug Session Guide |
 | `guidelines/debug-dump.md` | Dump Analysis Guide |
+| `guidelines/run-probe-classes.md` | run Command — AI Guidelines (probe classes, scratchWorkspace) |
 | `guidelines/branch-workflow.md` | Branch Workflow |
 | `guidelines/workflow-detailed.md` | Development Workflow (Detailed) |
 | `guidelines/object-creation.md` | Object Creation (XML metadata, local classes) |

package/abap/guidelines/debug-session.md

@@ -166,7 +166,7 @@ abapgit-agent debug stack  --json                        # call stack (shows whi
 abapgit-agent debug delete --all
 ```
 
-> **If the stale debug daemon holds an ABAP lock** (symptom: `Requested object EZABAPGIT is currently locked by user CAIS`):
+> **If the stale debug daemon holds an ABAP lock** (symptom: `Requested object EZABAPGIT is currently locked by user <USER>`):
 > ```bash
 > pkill -f "debug-daemon"   # kills daemon, SIGTERM triggers session.terminate() internally
 > ```

package/abap/guidelines/run-probe-classes.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: run Command Guide
+nav_order: 18
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# run Command — AI Guidelines
+
+## Never Run Proactively
+
+`abapgit-agent run` executes live ABAP code. **Never call it unless the user explicitly asks.**
+
+A class implementing `IF_OO_ADT_CLASSRUN` can do anything — modify database records, send emails, trigger RFCs. The interface signature gives no indication of side effects.
+
+```
+User: "Write a class that reads flight data and prints it"
+→ ✓ Create the class, pull it, STOP. Do NOT run it.
+→ ✓ Tell the user: "Class is activated. Run with: abapgit-agent run --class ZCL_MY_CLASS"
+
+User: "Now run it"
+→ ✓ Run it
+```
+
+---
+
+## Probe Classes and `scratchWorkspace`
+
+### Decision flow
+
+```
+User asks to create a probe class
+├── disableProbeClasses = false / not set  →  create in current project (default)
+└── disableProbeClasses = true
+    ├── scratchWorkspace configured  →  create there (see workflow below)
+    └── scratchWorkspace not configured  →  refuse, guide user to set it up
+```
+
+### When `disableProbeClasses = true` and `scratchWorkspace` is configured
+
+**Naming** — derive from `scratchWorkspace` config in `.abapGitAgent`:
+- `classPrefix` (default: `ZCL_{USER}_`) + `<PURPOSE>`, max 30 chars
+- Example: user=`JOHN`, purpose=`OPEN_TRANSPORTS` → `ZCL_JOHN_OPEN_TRANSPORTS`
+- If name already exists in `{path}/src/`, append `_2`, `_3`, etc.
+
+**Workflow:**
+1. Read `{path}/.abapGitAgent` to confirm `folder` property (e.g. `/src/`)
+2. Write class files in `{path}/src/`
+3. Commit and push from `{path}`:
+   ```bash
+   cd {path} && git add . && git commit -m "probe: <description>" && git push
+   ```
+4. Activate:
+   ```bash
+   cd {path} && abapgit-agent pull --files src/<classname>.clas.abap
+   ```
+5. Tell user (do NOT auto-run):
+   ```
+   Class activated. Run with: abapgit-agent run --class <CLASSNAME>
+   ```
+   Run the command from the original project directory, not `{path}`.
+
+### When `disableProbeClasses = true` and `scratchWorkspace` is NOT configured
+
+Refuse and tell the user to configure `scratchWorkspace` in `.abapGitAgent`.
+→ See `docs/run-command.md` (Scratch Workspace section) for setup instructions.

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, getConflictSettings, getTransportSettings } = require('../src/config');
+const { loadConfig, getTransport, isAbapIntegrationEnabled, getSafeguards, getConflictSettings, getTransportSettings, getScratchWorkspace } = require('../src/config');
 
 // Get terminal width for responsive table
 const getTermWidth = () => process.stdout.columns || 80;
@@ -52,6 +52,7 @@ async function main() {
     where: require('../src/commands/where'),
     dump: require('../src/commands/dump'),
     debug: require('../src/commands/debug'),
+    run: require('../src/commands/run'),
     ref: require('../src/commands/ref'),
     init: require('../src/commands/init'),
     pull: require('../src/commands/pull'),
@@ -105,7 +106,8 @@ To enable integration:
       getTransport,
       getSafeguards,
       getConflictSettings,
-      getTransportSettings
+      getTransportSettings,
+      getScratchWorkspace
     };
 
     // Execute command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.11.4",
+  "version": "1.12.1",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [

package/src/commands/init.js

@@ -129,7 +129,7 @@ Usage:
 
 Description:
   Initialize local repository configuration.
-  Creates .abapGitAgent, .gitignore, CLAUDE.md, and guidelines folder.
+  Creates .abapGitAgent, .abapgit.xml, .gitignore, CLAUDE.md, and guidelines folder.
 
 Options:
   --package <PACKAGE>             ABAP package name (required)
@@ -500,6 +500,34 @@ Uncomment and edit the rows that differ from the defaults in \`guidelines/object
       console.error(`Error creating folder: ${error.message}`);
     }
 
+    // Create .abapgit.xml with correct STARTING_FOLDER so abapGit's remove_ignored_files()
+    // keeps files inside the source folder. Without this file the stored starting_folder in
+    // the ABAP persistence may not match the actual folder, causing all remote files to be
+    // silently ignored and pull to return ACTIVATED_COUNT=0 with an empty log.
+    const abapgitXmlPath = pathModule.join(process.cwd(), '.abapgit.xml');
+    if (!fs.existsSync(abapgitXmlPath)) {
+      const language = (config.language || 'E').toUpperCase().charAt(0);
+      const abapgitXml = `<?xml version="1.0" encoding="utf-8"?>
+<asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+ <asx:values>
+  <DATA>
+   <MASTER_LANGUAGE>${language}</MASTER_LANGUAGE>
+   <STARTING_FOLDER>${folder}</STARTING_FOLDER>
+   <FOLDER_LOGIC>${folderLogic}</FOLDER_LOGIC>
+  </DATA>
+ </asx:values>
+</asx:abap>
+`;
+      try {
+        fs.writeFileSync(abapgitXmlPath, abapgitXml);
+        console.log(`✅ Created .abapgit.xml (STARTING_FOLDER=${folder}, FOLDER_LOGIC=${folderLogic})`);
+      } catch (error) {
+        console.error(`Error creating .abapgit.xml: ${error.message}`);
+      }
+    } else {
+      console.log(`✅ .abapgit.xml already exists, skipped`);
+    }
+
     console.log(`
 📋 Next steps:
    1. Edit .abapGitAgent with your ABAP credentials (host, user, password)

package/src/commands/pull.js

@@ -3,6 +3,8 @@
  */
 
 const { printHttpError } = require('../utils/format-error');
+const fs = require('fs');
+const pathModule = require('path');
 
 module.exports = {
   name: 'pull',
@@ -84,6 +86,20 @@ module.exports = {
         console.error('   Example: --files src/zcl_my_class.clas.abap');
         process.exit(1);
       }
+
+      // Validate that every specified file exists on disk.
+      // Skip when --url is explicit: the files belong to a different repository
+      // and won't be present in the current working directory.
+      if (urlArgIndex === -1) {
+        const fs = require('fs');
+        const missingFiles = files.filter(f => !fs.existsSync(f));
+        if (missingFiles.length > 0) {
+          console.error('❌ Error: the following file(s) do not exist:');
+          missingFiles.forEach(f => console.error(`     ${f}`));
+          console.error('   Check the path and try again.');
+          process.exit(1);
+        }
+      }
     }
 
     // SAFEGUARD 2: Check if files are required but not provided
@@ -102,22 +118,30 @@ module.exports = {
     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
-        }
+      // Check repository status — confirms the repo is registered and tells us
+      // whether a transport is required. If the check fails, abort: pulling into
+      // an uninitialised repository does not make sense.
+      let transportRequired = false;
+      let statusResult;
+      try {
+        const config = loadConfig();
+        const http = new AbapHttp(config);
+        const csrfToken = await http.fetchCsrfToken();
+        statusResult = await http.post('/sap/bc/z_abapgit_agent/status', { url: gitUrl }, { csrfToken });
+      } catch (e) {
+        console.error(`❌ Repository status check failed: ${e.message}`);
+        console.error('   Make sure the repository is registered with abapgit-agent (run "abapgit-agent create").');
+        process.exit(1);
+      }
+
+      if (!statusResult || statusResult.status === 'Not found') {
+        console.error(`❌ Repository not found in ABAP system: ${gitUrl}`);
+        console.error('   Run "abapgit-agent create" to register it first.');
+        process.exit(1);
+      }
+
+      if (statusResult.transport_required === true || statusResult.transport_required === 'true') {
+        transportRequired = true;
       }
 
       if (transportRequired) {
@@ -147,10 +171,10 @@ module.exports = {
       }
     }
 
-    await this.pull(gitUrl, branch, files, transportRequest, loadConfig, AbapHttp, jsonOutput, undefined, conflictMode);
+    await this.pull(gitUrl, branch, files, transportRequest, loadConfig, AbapHttp, jsonOutput, undefined, conflictMode, verbose);
   },
 
-  async pull(gitUrl, branch = 'main', files = null, transportRequest = null, loadConfig, AbapHttp, jsonOutput = false, gitCredentials = undefined, conflictMode = 'abort') {
+  async pull(gitUrl, branch = 'main', files = null, transportRequest = null, loadConfig, AbapHttp, jsonOutput = false, gitCredentials = undefined, conflictMode = 'abort', verbose = false) {
     const TERM_WIDTH = process.stdout.columns || 80;
 
     if (!jsonOutput) {
@@ -196,12 +220,26 @@ module.exports = {
 
       const result = await http.post('/sap/bc/z_abapgit_agent/pull', data, { csrfToken });
 
+      // Detect missing .abapgit.xml — without it abapGit's stored starting_folder
+      // may not match the actual source folder, causing pull to silently return ACTIVATED_COUNT=0
+      const missingAbapgitXml = fs.existsSync(pathModule.join(process.cwd(), '.git')) &&
+          !fs.existsSync(pathModule.join(process.cwd(), '.abapgit.xml'));
+
       // JSON output mode
       if (jsonOutput) {
+        if (missingAbapgitXml) {
+          result.missing_abapgit_xml = true;
+        }
         console.log(JSON.stringify(result, null, 2));
         return result;
       }
 
+      if (missingAbapgitXml) {
+        console.warn('⚠️  .abapgit.xml not found in repository root.');
+        console.warn('   Pull may return ACTIVATED_COUNT=0 if the ABAP-side starting_folder is wrong.');
+        console.warn('   Run: abapgit-agent init --package <PACKAGE> to create it.\n');
+      }
+
       console.log('\n');
 
       // Display raw result for debugging
@@ -284,11 +322,9 @@ module.exports = {
 
       if (success === 'X' || success === true) {
         console.log(`✅ Pull completed successfully!`);
-        console.log(`   Job ID: ${jobId || 'N/A'}`);
         console.log(`   Message: ${message || 'N/A'}`);
       } else {
         console.error(`❌ Pull completed with errors!`);
-        console.error(`   Job ID: ${jobId || 'N/A'}`);
         console.error(`   Message: ${message || 'N/A'}`);
       }
 

package/src/commands/run.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * run command — Execute an ABAP program or class and display its output.
+ *
+ * Programs (--program):
+ *   POST /sap/bc/adt/programs/programrun/{name}
+ *   Content-Type: application/vnd.sap.adt.programs.programRun+xml
+ *   Accept: text/plain
+ *   Note: SAP's ADT handler (CL_SEDI_ADT_PROGRAMRUN) calls SUBMIT with no
+ *         WITH additions — runtime parameters cannot be passed. The program
+ *         always runs with its coded defaults.
+ *
+ * Classes (--class):
+ *   POST /sap/bc/adt/oo/classrun/{name}
+ *   Accept: text/plain
+ *   Requires the class to implement IF_OO_ADT_CLASSRUN.
+ *   out->write() output is returned as plain text.
+ */
+
+const { AdtHttp } = require('../utils/adt-http');
+
+const PROGRAM_RUN_XML =
+  '<?xml version="1.0" encoding="UTF-8"?>\n' +
+  '<adtprog:programRun xmlns:adtprog="http://www.sap.com/adt/programs/programs"/>';
+
+module.exports = {
+  name: 'run',
+  description: 'Execute an ABAP program or class (IF_OO_ADT_CLASSRUN) and display its output',
+  requiresAbapConfig: true,
+  requiresVersionCheck: false,
+
+  async execute(args, context) {
+    const { loadConfig, getSafeguards } = context;
+
+    // Check project-level safeguards
+    const safeguards = getSafeguards();
+    if (safeguards.disableRun) {
+      console.error('❌ Error: run command is disabled for this project\n');
+      if (safeguards.reason) {
+        console.error(`Reason: ${safeguards.reason}\n`);
+      }
+      console.error('The run command has been disabled in .abapgit-agent.json');
+      console.error('Please contact the project maintainer to enable it.');
+      process.exit(1);
+    }
+
+    // Parse arguments
+    let programName = null;
+    let className = null;
+    let jsonOutput = false;
+
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--program' && args[i + 1]) {
+        programName = args[++i].toUpperCase();
+      } else if (args[i] === '--class' && args[i + 1]) {
+        className = args[++i].toUpperCase();
+      } else if (args[i] === '--json') {
+        jsonOutput = true;
+      }
+    }
+
+    if (programName && className) {
+      console.error('Error: --program and --class are mutually exclusive');
+      process.exit(1);
+    }
+
+    if (!programName && !className) {
+      console.error('Error: either --program or --class is required');
+      console.error('Usage: abapgit-agent run --program <NAME>');
+      console.error('       abapgit-agent run --class <NAME>');
+      process.exit(1);
+    }
+
+    const config = loadConfig();
+    const adt = new AdtHttp(config);
+
+    if (!adt.csrfToken) {
+      await adt.fetchCsrfToken();
+    }
+
+    let urlPath, body, requestOptions, targetName;
+
+    if (className) {
+      targetName = className;
+      urlPath = `/sap/bc/adt/oo/classrun/${className}`;
+      body = '';
+      requestOptions = { accept: 'text/plain' };
+    } else {
+      targetName = programName;
+      urlPath = `/sap/bc/adt/programs/programrun/${programName}`;
+      body = PROGRAM_RUN_XML;
+      requestOptions = {
+        contentType: 'application/vnd.sap.adt.programs.programRun+xml',
+        accept: 'text/plain'
+      };
+    }
+
+    let response;
+    try {
+      response = await adt.request('POST', urlPath, body, requestOptions);
+    } catch (err) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({ success: false, target: targetName, error: err.message || String(err) }));
+      } else {
+        console.error(`Error: ${err.message || err}`);
+      }
+      process.exit(1);
+    }
+
+    const output = (response.body || '').trimEnd();
+
+    if (jsonOutput) {
+      const key = className ? 'class' : 'program';
+      console.log(JSON.stringify({ success: true, [key]: targetName, output }));
+    } else {
+      console.log('\n--- Output ---');
+      console.log(output || '(no output)');
+      console.log('--------------');
+      console.log(`✅ Completed: ${targetName}`);
+    }
+  }
+};

package/src/config.js

@@ -122,6 +122,8 @@ function getSafeguards() {
     return {
       requireFilesForPull: projectConfig.safeguards.requireFilesForPull === true,
       disablePull: projectConfig.safeguards.disablePull === true,
+      disableRun: projectConfig.safeguards.disableRun === true,
+      disableProbeClasses: projectConfig.safeguards.disableProbeClasses === true,
       reason: projectConfig.safeguards.reason || null
     };
   }
@@ -130,6 +132,8 @@ function getSafeguards() {
   return {
     requireFilesForPull: false,
     disablePull: false,
+    disableRun: false,
+    disableProbeClasses: false,
     reason: null
   };
 }
@@ -199,6 +203,22 @@ function getTransportSettings() {
   return { allowCreate: true, allowRelease: true, reason: null };
 }
 
+/**
+ * Get scratch workspace configuration from personal config (.abapGitAgent)
+ * Used by AI to create probe/throwaway ABAP classes outside the current project
+ * @returns {{ path: string, classPrefix: string, programPrefix: string }|null}
+ */
+function getScratchWorkspace() {
+  const cfg = loadConfig();
+  if (!cfg.scratchWorkspace) return null;
+  const user = (cfg.user || 'PROBE').toUpperCase();
+  return {
+    path: cfg.scratchWorkspace.path || null,
+    classPrefix: cfg.scratchWorkspace.classPrefix || `ZCL_${user}_`,
+    programPrefix: cfg.scratchWorkspace.programPrefix || `Z${user}_`
+  };
+}
+
 module.exports = {
   loadConfig,
   getAbapConfig,
@@ -211,5 +231,6 @@ module.exports = {
   getConflictSettings,
   loadProjectConfig,
   getTransportHookConfig,
-  getTransportSettings
+  getTransportSettings,
+  getScratchWorkspace
 };