abapgit-agent 1.11.4 → 1.12.0

package/abap/CLAUDE.md

@@ -225,7 +225,23 @@ 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 |
 |---|---|---|
@@ -236,6 +252,7 @@ Quick start:
 ```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 run --class ZCL_MY_RUNNER       # execute and inspect output
 ```
 → 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 +343,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
@@ -384,6 +408,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.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [

package/src/commands/pull.js

@@ -284,11 +284,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
 };