@mcp-abap-adt/adt-clients 0.1.0

package/dist/utils/lockStateManager.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Lock State Manager - persists lock handles and session IDs to filesystem
+ * Allows recovery and cleanup of locks after crashes or interruptions
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LockStateManager = void 0;
+exports.getLockStateManager = getLockStateManager;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class LockStateManager {
+    lockFilePath;
+    registry;
+    constructor(lockDir = '.locks') {
+        // Create locks directory if it doesn't exist
+        const baseDir = path.resolve(process.cwd(), lockDir);
+        if (!fs.existsSync(baseDir)) {
+            fs.mkdirSync(baseDir, { recursive: true });
+        }
+        this.lockFilePath = path.join(baseDir, 'active-locks.json');
+        this.registry = this.loadRegistry();
+    }
+    /**
+     * Load lock registry from file
+     */
+    loadRegistry() {
+        if (fs.existsSync(this.lockFilePath)) {
+            try {
+                const data = fs.readFileSync(this.lockFilePath, 'utf-8');
+                return JSON.parse(data);
+            }
+            catch (error) {
+                console.warn(`Failed to load lock registry: ${error}`);
+                return { locks: [] };
+            }
+        }
+        return { locks: [] };
+    }
+    /**
+     * Save lock registry to file
+     */
+    saveRegistry() {
+        try {
+            fs.writeFileSync(this.lockFilePath, JSON.stringify(this.registry, null, 2), 'utf-8');
+        }
+        catch (error) {
+            console.error(`Failed to save lock registry: ${error}`);
+        }
+    }
+    /**
+     * Register a new lock
+     */
+    registerLock(lock) {
+        const lockState = {
+            ...lock,
+            timestamp: Date.now(),
+            pid: process.pid,
+        };
+        // Remove old lock for same object if exists
+        this.registry.locks = this.registry.locks.filter(l => !(l.objectType === lock.objectType &&
+            l.objectName === lock.objectName &&
+            l.functionGroupName === lock.functionGroupName));
+        this.registry.locks.push(lockState);
+        this.saveRegistry();
+    }
+    /**
+     * Remove lock from registry
+     */
+    removeLock(objectType, objectName, functionGroupName) {
+        this.registry.locks = this.registry.locks.filter(l => !(l.objectType === objectType &&
+            l.objectName === objectName &&
+            l.functionGroupName === functionGroupName));
+        this.saveRegistry();
+    }
+    /**
+     * Get lock for specific object
+     */
+    getLock(objectType, objectName, functionGroupName) {
+        return this.registry.locks.find(l => l.objectType === objectType &&
+            l.objectName === objectName &&
+            l.functionGroupName === functionGroupName);
+    }
+    /**
+     * Get all active locks
+     */
+    getAllLocks() {
+        return [...this.registry.locks];
+    }
+    /**
+     * Get stale locks (older than threshold)
+     */
+    getStaleLocks(maxAgeMs = 30 * 60 * 1000) {
+        const now = Date.now();
+        return this.registry.locks.filter(l => now - l.timestamp > maxAgeMs);
+    }
+    /**
+     * Get locks from dead processes
+     */
+    getDeadProcessLocks() {
+        return this.registry.locks.filter(l => {
+            try {
+                // Check if process is still running
+                process.kill(l.pid, 0);
+                return false; // Process exists
+            }
+            catch (e) {
+                return true; // Process doesn't exist
+            }
+        });
+    }
+    /**
+     * Clean up stale locks
+     */
+    cleanupStaleLocks(maxAgeMs) {
+        const staleLocks = this.getStaleLocks(maxAgeMs);
+        const deadProcessLocks = this.getDeadProcessLocks();
+        const toCleanup = [...new Set([...staleLocks, ...deadProcessLocks])];
+        toCleanup.forEach(lock => {
+            this.removeLock(lock.objectType, lock.objectName, lock.functionGroupName);
+        });
+        return toCleanup;
+    }
+    /**
+     * Clear all locks
+     */
+    clearAll() {
+        this.registry = { locks: [] };
+        this.saveRegistry();
+    }
+}
+exports.LockStateManager = LockStateManager;
+// Global instance
+let globalManager = null;
+function getLockStateManager(lockDir) {
+    if (!globalManager) {
+        globalManager = new LockStateManager(lockDir);
+    }
+    return globalManager;
+}

package/dist/utils/sessionUtils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Session Management Utilities for SAP ADT Stateful Operations
+ *
+ * This module provides centralized utilities for managing stateful sessions
+ * when interacting with SAP ADT (ABAP Development Tools) API.
+ *
+ * Key concepts:
+ * - Session ID (sap-adt-connection-id): Unique identifier for the entire operation
+ *   Must be the SAME for all requests (LOCK → PUT → UNLOCK) within one operation
+ *
+ * - Request ID (sap-adt-request-id): Unique identifier for each individual request
+ *   Must be DIFFERENT for every request within a session
+ *
+ * - Stateful Session: Required for operations that modify ABAP objects
+ *   (create/update source code, lock management, transport handling)
+ */
+import { AxiosResponse } from 'axios';
+import { AbapConnection } from '@mcp-abap-adt/connection';
+/**
+ * Generate unique session ID for ADT stateful operations
+ *
+ * This ID must be used consistently across all requests within a single operation
+ * (e.g., LOCK → PUT → UNLOCK sequence). Using different session IDs will cause
+ * "invalid lock handle" errors.
+ *
+ * Format: 32-character hexadecimal string (UUID without hyphens)
+ * Example: "a1b2c3d4e5f67890123456789abcdef0"
+ *
+ * @returns Unique session ID for sap-adt-connection-id header
+ */
+export declare function generateSessionId(): string;
+/**
+ * Generate unique request ID for each individual ADT request
+ *
+ * Each request within a session must have a different request ID.
+ * This is used for tracking and debugging purposes.
+ *
+ * Format: 32-character hexadecimal string (UUID without hyphens)
+ * Example: "f0e1d2c3b4a5968778695a4b3c2d1e0f"
+ *
+ * @returns Unique request ID for sap-adt-request-id header
+ */
+export declare function generateRequestId(): string;
+/**
+ * Make ADT request with stateful session management
+ *
+ * This is a wrapper around connection.makeAdtRequest that automatically adds
+ * the required headers for stateful ADT operations:
+ * - sap-adt-connection-id: Session identifier (must be same for all requests)
+ * - sap-adt-request-id: Request identifier (must be unique for each request)
+ * - x-sap-adt-sessiontype: "stateful" (declares stateful session mode)
+ * - X-sap-adt-profiling: "server-time" (optional performance profiling)
+ *
+ * CRITICAL RULES:
+ * 1. Use the SAME sessionId for all requests in one operation (LOCK/PUT/UNLOCK)
+ * 2. Each call to this function generates a NEW unique request ID automatically
+ * 3. Cookies are managed automatically by BaseAbapConnection
+ * 4. Always unlock in try/finally block to prevent orphaned locks
+ *
+ * @param connection - ABAP connection instance
+ * @param url - ADT API endpoint URL (can be relative or absolute)
+ * @param method - HTTP method ('GET', 'POST', 'PUT', 'DELETE')
+ * @param sessionId - Session ID from generateSessionId() - MUST be same for all related requests
+ * @param data - Optional request body (source code, XML payload, etc.)
+ * @param additionalHeaders - Optional custom headers to merge with session headers
+ * @returns Promise with Axios response
+ */
+export declare function makeAdtRequestWithSession(connection: AbapConnection, url: string, method: string, sessionId: string, data?: any, additionalHeaders?: Record<string, string>): Promise<AxiosResponse>;
+//# sourceMappingURL=sessionUtils.d.ts.map

package/dist/utils/sessionUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionUtils.d.ts","sourceRoot":"","sources":["../../src/utils/sessionUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,cAAc,EAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,GAAG,EACV,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,OAAO,CAAC,aAAa,CAAC,CA2BxB"}

package/dist/utils/sessionUtils.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Session Management Utilities for SAP ADT Stateful Operations
+ *
+ * This module provides centralized utilities for managing stateful sessions
+ * when interacting with SAP ADT (ABAP Development Tools) API.
+ *
+ * Key concepts:
+ * - Session ID (sap-adt-connection-id): Unique identifier for the entire operation
+ *   Must be the SAME for all requests (LOCK → PUT → UNLOCK) within one operation
+ *
+ * - Request ID (sap-adt-request-id): Unique identifier for each individual request
+ *   Must be DIFFERENT for every request within a session
+ *
+ * - Stateful Session: Required for operations that modify ABAP objects
+ *   (create/update source code, lock management, transport handling)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSessionId = generateSessionId;
+exports.generateRequestId = generateRequestId;
+exports.makeAdtRequestWithSession = makeAdtRequestWithSession;
+const crypto = __importStar(require("crypto"));
+const connection_1 = require("@mcp-abap-adt/connection");
+/**
+ * Generate unique session ID for ADT stateful operations
+ *
+ * This ID must be used consistently across all requests within a single operation
+ * (e.g., LOCK → PUT → UNLOCK sequence). Using different session IDs will cause
+ * "invalid lock handle" errors.
+ *
+ * Format: 32-character hexadecimal string (UUID without hyphens)
+ * Example: "a1b2c3d4e5f67890123456789abcdef0"
+ *
+ * @returns Unique session ID for sap-adt-connection-id header
+ */
+function generateSessionId() {
+    return crypto.randomUUID().replace(/-/g, '');
+}
+/**
+ * Generate unique request ID for each individual ADT request
+ *
+ * Each request within a session must have a different request ID.
+ * This is used for tracking and debugging purposes.
+ *
+ * Format: 32-character hexadecimal string (UUID without hyphens)
+ * Example: "f0e1d2c3b4a5968778695a4b3c2d1e0f"
+ *
+ * @returns Unique request ID for sap-adt-request-id header
+ */
+function generateRequestId() {
+    return crypto.randomUUID().replace(/-/g, '');
+}
+/**
+ * Make ADT request with stateful session management
+ *
+ * This is a wrapper around connection.makeAdtRequest that automatically adds
+ * the required headers for stateful ADT operations:
+ * - sap-adt-connection-id: Session identifier (must be same for all requests)
+ * - sap-adt-request-id: Request identifier (must be unique for each request)
+ * - x-sap-adt-sessiontype: "stateful" (declares stateful session mode)
+ * - X-sap-adt-profiling: "server-time" (optional performance profiling)
+ *
+ * CRITICAL RULES:
+ * 1. Use the SAME sessionId for all requests in one operation (LOCK/PUT/UNLOCK)
+ * 2. Each call to this function generates a NEW unique request ID automatically
+ * 3. Cookies are managed automatically by BaseAbapConnection
+ * 4. Always unlock in try/finally block to prevent orphaned locks
+ *
+ * @param connection - ABAP connection instance
+ * @param url - ADT API endpoint URL (can be relative or absolute)
+ * @param method - HTTP method ('GET', 'POST', 'PUT', 'DELETE')
+ * @param sessionId - Session ID from generateSessionId() - MUST be same for all related requests
+ * @param data - Optional request body (source code, XML payload, etc.)
+ * @param additionalHeaders - Optional custom headers to merge with session headers
+ * @returns Promise with Axios response
+ */
+async function makeAdtRequestWithSession(connection, url, method, sessionId, data, additionalHeaders) {
+    // Resolve to full URL if relative path provided
+    const baseUrl = await connection.getBaseUrl();
+    const fullUrl = url.startsWith('http') ? url : `${baseUrl}${url}`;
+    // Generate unique request ID for this specific request
+    const requestId = generateRequestId();
+    // Build headers with stateful session identifiers
+    const headers = {
+        'sap-adt-connection-id': sessionId, // Same for all requests in operation
+        'sap-adt-request-id': requestId, // Unique for this request
+        'x-sap-adt-sessiontype': 'stateful', // Declares stateful session
+        'X-sap-adt-profiling': 'server-time', // Performance profiling
+        ...additionalHeaders // Merge any custom headers
+    };
+    // Make request using connection
+    const timeout = (0, connection_1.getTimeout)('default');
+    return connection.makeAdtRequest({
+        url: fullUrl,
+        method,
+        timeout,
+        data,
+        params: undefined,
+        headers
+    });
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@mcp-abap-adt/adt-clients",
+  "version": "0.1.0",
+  "description": "ADT clients for SAP ABAP systems - Read-only, CRUD, and Management operations",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "adt-lock-object": "./bin/lock-object.js",
+    "adt-unlock-object": "./bin/unlock-object.js",
+    "adt-manage-locks": "./bin/manage-locks.js",
+    "adt-manage-sessions": "./bin/manage-sessions.js",
+    "adt-unlock-objects": "./bin/unlock-test-objects.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "abap",
+    "sap",
+    "adt",
+    "clients",
+    "read-only",
+    "crud",
+    "mcp"
+  ],
+  "author": "Oleksii Kyslytsia <oleksij.kyslytsja@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/fr0ster/mcp-abap-adt-clients#readme",
+  "bugs": {
+    "url": "https://github.com/fr0ster/mcp-abap-adt-clients/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fr0ster/mcp-abap-adt-clients.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "build": "npm run --silent clean && npx tsc -p tsconfig.json",
+    "build:fast": "npx tsc -p tsconfig.json",
+    "test": "jest --runInBand",
+    "test:sequential": "node scripts/run-tests-sequential.js",
+    "test:module": "node scripts/test-module.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@mcp-abap-adt/connection": "^0.1.3",
+    "fast-xml-parser": "^5.2.5",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.2.1",
+    "dotenv": "^17.2.1",
+    "jest": "^30.0.5",
+    "ts-jest": "^29.4.1",
+    "typescript": "^5.9.2",
+    "yaml": "^2.8.1"
+  }
+}
+