@mcp-abap-adt/adt-clients 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Oleksii Kyslytsia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,184 @@
+# @mcp-abap-adt/adt-clients
+
+ADT (ABAP Development Tools) clients for SAP ABAP systems with a **Builder-first API**.  
+Low-level helpers stay internal; consumers interact via Builders and high-level clients (Management, Lock, Validation).
+
+## Features
+
+- ✅ **Builder-first workflow** – every supported object type exposes a fluent Builder (`ClassBuilder`, `TableBuilder`, …) that wraps validate/create/lock/update/activate in one chain.
+- ✅ **High-level clients** – `ManagementClient`, `LockClient`, `ValidationClient` cover cross-object tasks (activation, ad-hoc locking, name validation) without touching internal modules.
+- ✅ **Stateful session propagation** – builders and clients keep the same `sap-adt-connection-id` across lock/update/unlock; session state can be exported/imported via the connection package.
+- ✅ **Lock registry + CLI** – persistent `.locks/active-locks.json` plus `adt-manage-locks` / `adt-unlock-objects` scripts to recover from crashes.
+- ✅ **Test-friendly logging** – `DEBUG_TESTS=true` for per-step output, `LOG_LOCKS=false` to silence `[LOCK] ...` lines.
+
+## Installation
+
+### As npm Package
+
+```bash
+# Install globally for CLI tools
+npm install -g @mcp-abap-adt/adt-clients
+
+# Or install in project
+npm install @mcp-abap-adt/adt-clients
+```
+
+### CLI Tools
+
+After global installation, you get 5 CLI commands:
+
+- `adt-lock-object` - Lock an object and save session
+- `adt-unlock-object` - Unlock using saved session
+- `adt-manage-locks` - View/manage lock registry
+- `adt-manage-sessions` - View/manage session files
+- `adt-unlock-objects` - Cleanup test objects
+
+See [CLI Tools documentation](./bin/README.md) for details.
+
+## Supported Object Types
+
+- **Classes** (CLAS/OC) - Full CRUD + run (if_oo_adt_classrun)
+- **Interfaces** (INTF/OI) - Full CRUD
+- **Programs** (PROG/P) - Full CRUD
+- **Function Groups** (FUGR/F) - Full CRUD
+- **Function Modules** (FUGR/FF) - Full CRUD
+- **Domains** (DOMA/DD) - Full CRUD
+- **Data Elements** (DTEL/DE) - Full CRUD
+- **CDS Views** (DDLS/DL) - Full CRUD
+- **Tables** (TABL/DT) - Read operations
+- **Structures** (TABL/DS) - Read operations
+- **Packages** (DEVC/K) - Create, read
+- **Transports** (TRNS/R3TR) - Create
+
+## Quick Start
+
+```typescript
+import { createAbapConnection } from '@mcp-abap-adt/connection';
+import { ClassBuilder, LockClient, ManagementClient } from '@mcp-abap-adt/adt-clients';
+
+const connection = createAbapConnection({
+  url: 'https://your-sap-system.example.com',
+  client: '100',
+  authType: 'basic',
+  username: process.env.SAP_USERNAME!,
+  password: process.env.SAP_PASSWORD!
+}, console);
+
+// Full builder workflow
+const builder = new ClassBuilder(connection, console, {
+  className: 'ZCL_MY_CLASS',
+  packageName: 'ZADT_BLD_PKG01',
+  description: 'Demo builder class',
+  transportRequest: 'E19K900001'
+});
+
+await builder
+  .setCode(`CLASS zcl_my_class DEFINITION PUBLIC.
+  PUBLIC SECTION.
+    METHODS: hello.
+ENDCLASS.
+
+CLASS zcl_my_class IMPLEMENTATION.
+  METHOD hello.
+    WRITE: 'Hello from builder'.
+  ENDMETHOD.
+ENDCLASS.`)
+  .validate()
+  .then(b => b.create())
+  .then(b => b.check('inactive'))
+  .then(b => b.lock())
+  .then(b => {
+    b.setCode(b.getState().sourceCode!.replace('builder', 'builder v2'));
+    return b.update();
+  })
+  .then(b => b.check('inactive'))
+  .then(b => b.unlock())
+  .then(b => b.activate())
+  .then(b => b.check('active'));
+
+// Ad-hoc management helpers
+const lockClient = new LockClient(connection);
+const mgmtClient = new ManagementClient(connection);
+
+const { lockHandle, sessionId } = await lockClient.lock({
+  objectType: 'class',
+  objectName: 'ZCL_MY_CLASS'
+});
+
+await mgmtClient.activateObjectsGroup([{ name: 'ZCL_MY_CLASS', uri: '/sap/bc/adt/oo/classes/zcl_my_class' }]);
+
+await lockClient.unlock({
+  objectType: 'class',
+  objectName: 'ZCL_MY_CLASS',
+  lockHandle,
+  sessionId
+});
+```
+
+> ℹ️ Need to persist the `sessionId` / cookies between processes? See [doc/architecture/STATEFUL_SESSION_GUIDE.md](../../doc/architecture/STATEFUL_SESSION_GUIDE.md) and the `@mcp-abap-adt/connection` README for details.
+
+## CLI Tools
+
+After installation, the following commands are available:
+
+### Manage Locks
+
+```bash
+# List all active locks
+adt-manage-locks list
+
+# Clean up stale locks
+adt-manage-locks cleanup
+
+# Unlock specific object
+adt-manage-locks unlock class ZCL_TEST
+```
+
+### Manage Sessions
+
+```bash
+# List all sessions
+adt-manage-sessions list
+
+# Show session details
+adt-manage-sessions info <sessionId>
+
+# Clean up stale sessions
+adt-manage-sessions cleanup
+```
+
+See [bin/README.md](bin/README.md) for details.
+
+## Builders & Clients
+
+- **Builders**: classes, interfaces, programs, domains, data elements, tables, structures, views, packages, transports, function groups, function modules.  
+  Each builder exposes `.validate()`, `.create()`, `.lock()`, `.update()`, `.activate()`, `.check()`, `.read()`, `.forceUnlock()`.
+- **ManagementClient**: batch activation + check operations.
+- **LockClient**: explicit lock/unlock helpers that integrate with the `.locks` registry (used by tests and CLI tools).
+- **ValidationClient**: name validation helper mirroring ADT validation endpoint.
+
+Refer to the TypeScript typings (`src/index.ts`) for the full API surface.
+
+## Documentation
+
+- **[Stateful Session Guide](docs/STATEFUL_SESSION_GUIDE.md)** – how Builders and clients manage `sessionId`, `lockHandle`, and the lock registry
+- **[Architecture](docs/reference/ARCHITECTURE.md)** – package structure and design decisions
+- **[Builder Test Pattern](docs/BUILDER_TEST_PATTERN.md)** – test structure and patterns for contributors
+- **[Test Configuration Schema](docs/TEST_CONFIG_SCHEMA.md)** – YAML test configuration reference
+
+## Logging
+
+- `DEBUG_TESTS=true` – verbose step-by-step logging for tests
+- `LOG_LOCKS=false` – disable `[LOCK] ...` lines (enabled by default)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for package-specific release notes.
+
+## License
+
+MIT
+
+## Author
+
+Oleksii Kyslytsia <oleksij.kyslytsja@gmail.com>

package/bin/README.md

@@ -0,0 +1,368 @@
+# CLI Utilities
+
+This directory contains command-line utilities for managing ADT client sessions and locks.
+
+## Overview of All Scripts
+
+| Command | Purpose | Use Case |
+|---------|---------|----------|
+| `adt-lock-object` | Lock an object and save session | Start work on object, persist session for later |
+| `adt-unlock-object` | Unlock object using saved session | Resume work and unlock after crash/restart |
+| `adt-manage-locks` | View/clean lock registry | Debug locks, cleanup stale locks |
+| `adt-manage-sessions` | View/clean session files | Debug sessions, cleanup old sessions |
+| `adt-unlock-objects` | Unlock predefined test objects | Cleanup after failed integration tests |
+
+### Key Differences
+
+**Lock/Unlock Pair (for production use):**
+- `adt-lock-object` + `adt-unlock-object` - Full workflow: lock → save session → restore session → unlock
+- Works with ANY object specified via CLI args
+- Designed for manual/scripted workflows
+
+**Management Tools (for debugging/maintenance):**
+- `adt-manage-locks` - View and manage lock registry only
+- `adt-manage-sessions` - View and manage session files only
+- Read-only inspection + cleanup operations
+
+**Test Cleanup (for testing):**
+- `adt-unlock-objects` - Hardcoded list of test objects from test-config.yaml
+- Used specifically for cleanup after integration test failures
+
+## Installation
+
+### Global Installation (Recommended)
+
+Install globally to use CLI commands from anywhere:
+
+```bash
+npm install -g @mcp-abap-adt/adt-clients
+```
+
+After global installation, all commands are available in your PATH:
+
+```bash
+adt-lock-object --help
+adt-unlock-object --help
+adt-manage-locks --help
+adt-manage-sessions --help
+```
+
+### Local Installation
+
+Install as a dependency in your project:
+
+```bash
+npm install @mcp-abap-adt/adt-clients
+```
+
+Run commands using npx:
+
+```bash
+npx adt-lock-object class ZCL_MY_CLASS
+npx adt-manage-locks list
+```
+
+### Development Installation
+
+For local development from repository:
+
+```bash
+cd packages/adt-clients
+npm install
+npm run build
+npm link  # Makes commands available globally
+```
+
+The following commands will be available:
+
+## Commands
+
+### adt-lock-object
+
+Lock an SAP object and save session state for later recovery.
+
+```bash
+# Lock a class
+adt-lock-object class ZCL_MY_CLASS
+
+# Lock with custom session ID
+adt-lock-object class ZCL_MY_CLASS --session-id my_work
+
+# Lock a function module
+adt-lock-object fm MY_FUNCTION --function-group Z_MY_FUGR
+
+# Lock a program
+adt-lock-object program Z_MY_PROGRAM
+```
+
+**What it does:**
+1. Connects to SAP and locks the object
+2. Saves session (cookies, CSRF token) to `.sessions/<session-id>.json`
+3. Registers lock handle in `.locks/active-locks.json`
+4. Prints unlock command for later use
+
+**Supported types:** class, program, interface, fm, domain, dataelement
+
+### adt-unlock-object
+
+Unlock an SAP object using previously saved session state.
+
+```bash
+# Unlock using saved session
+adt-unlock-object class ZCL_MY_CLASS --session-id my_work
+
+# Unlock function module
+adt-unlock-object fm MY_FUNCTION --function-group Z_MY_FUGR --session-id my_work
+```
+
+**What it does:**
+1. Loads session from `.sessions/<session-id>.json`
+2. Restores session state to new connection
+3. Retrieves lock handle from `.locks/active-locks.json`
+4. Unlocks the object on SAP server
+5. Removes lock from registry
+
+**Note:** Requires `--session-id` used with `adt-lock-object`
+
+### adt-manage-locks
+
+Manage persistent lock registry - view, cleanup, and force unlock.
+
+```bash
+# List all active locks
+adt-manage-locks list
+
+# Clean up stale locks (>30 min or dead processes)
+adt-manage-locks cleanup
+
+# Force unlock specific object on SAP server
+adt-manage-locks unlock class ZCL_TEST
+adt-manage-locks unlock fm MY_FUNCTION Z_MY_FUGR
+
+# Clear all locks from registry
+adt-manage-locks clear
+```
+
+**What it does:**
+- `list` - Shows all locks with session ID, handle, object, timestamp, PID
+- `cleanup` - Removes stale locks (>30min old or dead processes)
+- `unlock` - Connects to SAP and force unlocks object, removes from registry
+- `clear` - Removes ALL locks from registry (doesn't unlock on SAP!)
+
+**Use case:** Debugging lock issues, cleanup after crashes
+
+### adt-manage-sessions
+
+Manage saved session files - view, inspect, and cleanup.
+
+```bash
+# List all sessions
+adt-manage-sessions list
+
+# View session details
+adt-manage-sessions info my_session_id
+
+# Clean up old sessions (>24 hours)
+adt-manage-sessions cleanup
+
+# Clear all sessions
+adt-manage-sessions clear
+```
+
+**What it does:**
+- `list` - Shows all session files with ID, timestamp, age, PID
+- `info` - Displays session details (cookies, CSRF token, metadata)
+- `cleanup` - Removes stale sessions (>24h old or dead processes)
+- `clear` - Deletes ALL session files
+
+**Use case:** Debugging session issues, inspect saved state, cleanup old files
+
+### adt-unlock-objects
+
+Unlock predefined test objects from test-config.yaml.
+
+```bash
+# Unlock all test objects defined in test-config.yaml
+adt-unlock-objects
+
+# Use custom config file
+adt-unlock-objects --config custom-test-config.yaml
+
+# Use custom locks directory
+adt-unlock-objects --locks-dir /custom/path/.locks
+```
+
+**What it does:**
+1. Reads test object list from `test-config.yaml`
+2. For each object: retrieves lock handle from registry
+3. Connects to SAP and unlocks object
+4. Removes lock from registry
+
+**Use case:** Cleanup after integration test failures when objects remain locked
+
+**Note:** Hardcoded to work with test objects only, not for general use
+
+## Common Options
+
+Most commands support:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--locks-dir <path>` | Lock registry directory | `.locks` |
+| `--sessions-dir <path>` | Sessions directory | `.sessions` |
+| `--env <path>` | Path to .env file | `.env` |
+| `--help, -h` | Show help message | - |
+
+## Workflow Examples
+
+### Daily Work on a Class
+
+```bash
+# Morning - lock class and start work
+adt-lock-object class ZCL_MY_WORK --session-id daily_work
+# Session ID: daily_work
+
+# ... work all day, make changes via other tools ...
+
+# Evening - unlock when done
+adt-unlock-object class ZCL_MY_WORK --session-id daily_work
+```
+
+### Recovery After Crash
+
+```bash
+# Process crashed while object was locked
+# Check what was locked
+adt-manage-locks list
+
+# Resume and unlock using saved session
+adt-unlock-object class ZCL_MY_CLASS --session-id <session-from-list>
+```
+
+### Integration Test Cleanup
+
+```bash
+# Tests failed and left objects locked
+# Quick cleanup of all test objects
+adt-unlock-objects
+```
+
+### Debug Session Issues
+
+```bash
+# See what sessions are saved
+adt-manage-sessions list
+
+# Inspect specific session
+adt-manage-sessions info my_session_id
+
+# Clean up old sessions
+adt-manage-sessions cleanup
+```
+
+## File Structure
+
+```
+.sessions/
+  ├── my_work_session.json       # Session state (cookies, CSRF)
+  └── lock_class_ZCL_TEST_*.json # Auto-generated session
+
+.locks/
+  └── active-locks.json           # Lock registry
+```
+
+## Environment Setup
+
+Required in `.env`:
+
+```bash
+SAP_URL=https://your-sap-system.com
+SAP_USERNAME=your_username
+SAP_PASSWORD=your_password
+```
+
+## Gitignore
+
+Ensure these directories are in `.gitignore`:
+
+```gitignore
+.sessions/
+.locks/
+```
+
+## See Also
+
+- [Session State Management](../docs/archive/SESSION_STATE_MANAGEMENT.md)
+- [Lock State Management](../docs/archive/LOCK_STATE_MANAGEMENT.md)
+- [Lock Recovery Test](../src/__tests__/integration/README_LOCK_RECOVERY.md)
+
+
+# Clear all locks from registry
+adt-manage-locks clear
+```
+
+### adt-manage-sessions
+
+Manage HTTP session state (cookies, CSRF tokens).
+
+```bash
+# List all active sessions
+adt-manage-sessions list
+
+# Show session details
+adt-manage-sessions info <sessionId>
+
+# Clean up stale sessions (>30 min or dead processes)
+adt-manage-sessions cleanup
+
+# Clear all sessions
+adt-manage-sessions clear
+```
+
+### adt-unlock-objects
+
+Unlock predefined test objects (used after failed tests).
+
+```bash
+adt-unlock-objects
+```
+
+## With npx
+
+You can also run these commands without installing:
+
+```bash
+npx @mcp-abap-adt/adt-clients adt-manage-locks list
+npx @mcp-abap-adt/adt-clients adt-manage-sessions list
+```
+
+## Configuration
+
+Commands require `.env` file in the project root with SAP connection details:
+
+```env
+SAP_URL=https://your-sap-system.com:443
+SAP_CLIENT=100
+SAP_USERNAME=your-username
+SAP_PASSWORD=your-password
+SAP_AUTH_TYPE=basic
+```
+
+For JWT authentication:
+```env
+SAP_AUTH_TYPE=jwt
+SAP_JWT_TOKEN=your-jwt-token
+```
+
+## Data Storage
+
+- **Locks**: `.locks/active-locks.json`
+- **Sessions**: `.sessions/<sessionId>.json`
+
+Both directories are in `.gitignore` and should not be committed.
+
+## Documentation
+
+For detailed information, see:
+- [Lock State Management](../docs/archive/LOCK_STATE_MANAGEMENT.md)
+- [Session State Management](../docs/archive/SESSION_STATE_MANAGEMENT.md)