abapgit-agent 1.0.0 → 1.1.0

package/docs/health-command.md

@@ -0,0 +1,89 @@
+# health Command Requirements
+
+## Overview
+
+Check if the ABAP REST API is healthy and accessible.
+
+## Command
+
+```bash
+abapgit-agent health
+```
+
+## Prerequisite
+
+- `.abapGitAgent` file exists with valid credentials, or environment variables are set
+
+## Tasks
+
+### 1. Load Configuration
+
+Read from `.abapGitAgent` or environment variables:
+- `host`
+- `sapport`
+- `client`
+- `user`
+- `password`
+- `language`
+
+### 2. Make Health Check Request
+
+**Endpoint:** `GET /health`
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "abap": "connected",
+  "version": "1.0.0"
+}
+```
+
+### 3. Display Result
+
+```bash
+$ abapgit-agent health
+{
+  "status": "healthy",
+  "abap": "connected",
+  "version": "1.0.0"
+}
+```
+
+---
+
+## Output
+
+| Status | Output |
+|--------|--------|
+| Healthy | JSON response with status |
+| Error | Error message with details |
+
+---
+
+## Error Handling
+
+| Error | Message |
+|-------|---------|
+| Connection failed | `Health check failed: <error message>` |
+| Invalid credentials | Authentication error |
+
+---
+
+## Example
+
+```bash
+# Check health
+abapgit-agent health
+
+# Output
+{
+  "status": "healthy",
+  "abap": "connected",
+  "version": "1.0.0"
+}
+```
+
+## Used By
+
+- `create` command - validates ABAP connection before creating repo

package/docs/import-command.md

@@ -0,0 +1,195 @@
+# import Command
+
+Import existing ABAP objects from a package into an existing abapGit online repository.
+
+## Command
+
+```bash
+abapgit-agent import
+abapgit-agent import --message "Your commit message"
+```
+
+## Prerequisites
+
+- Repository already exists in ABAP (created via abapGit UI or `create` command)
+- Package has objects to import
+- GitHub credentials configured in `.abapGitAgent`
+
+## Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `--message` | No | `feat: initial import from ABAP package <package>` | Commit message |
+| `--help` | No | - | Show help |
+
+## Configuration
+
+### .abapGitAgent
+
+Add GitHub credentials to `.abapGitAgent`:
+
+```json
+{
+  "gitUsername": "<your-github-username>",
+  "gitPassword": "ghp_your_github_token"
+}
+```
+
+### Environment Variables
+
+```bash
+export GIT_USERNAME="<your-github-username>"
+export GIT_PASSWORD="ghp_your_github_token"
+```
+
+### GitHub Personal Access Token
+
+1. Create a PAT at:
+   - GitHub.com: https://github.com/settings/tokens
+
+2. Select scopes:
+   - `repo` - Full control of private repositories
+   - Or `public_repo` if your repo is public
+
+## How It Works
+
+1. **Validate** - Check repository URL exists
+2. **Find Repo** - Locate abapGit repository by git URL
+3. **Configure Credentials** - Set git credentials from config
+4. **Refresh** - Get latest local files from package
+5. **Stage** - Create stage with all files
+6. **Commit** - Commit with message
+7. **Push** - Push to remote
+
+## Workflow
+
+### Full Development Cycle
+
+```
+1. Develop in ABAP (SAP GUI, ADT)
+   └─> Create/modify objects in package
+
+2. abapgit-agent import
+   └─> Stages, commits, and pushes to git
+
+3. git pull (optional, in local repo)
+   └─> Get files to local folder
+
+4. Repeat
+```
+
+## Output
+
+### Success
+
+```
+✅ Objects imported successfully!
+   Files staged: 27
+   Commit: feat: initial import from ABAP package AUD_TAG
+```
+
+### With Custom Message
+
+```
+✅ Objects imported successfully!
+   Files staged: 15
+   Commit: My custom import message
+```
+
+### Error - Repository Not Found
+
+```
+❌ Import failed
+   Error: Repository not found. Run "abapgit-agent create" or create in abapGit UI first.
+```
+
+### Error - No Objects Found
+
+```
+❌ Import failed
+   Error: No objects found in package ZMY_PACKAGE
+```
+
+### Error - GitHub Credentials
+
+```
+❌ Import failed
+   Error: Unauthorized access to resource (HTTP 401)
+```
+
+## Troubleshooting
+
+### HTTP 401 Unauthorized
+
+GitHub credentials not configured or invalid:
+
+1. Create a GitHub Personal Access Token
+2. Add to `.abapGitAgent`:
+
+```json
+{
+  "gitUsername": "<your-github-username>",
+  "gitPassword": "ghp_your_token"
+}
+```
+
+### Repository Not Found
+
+The repository must exist in abapGit:
+
+1. Run `abapgit-agent create` to create it, OR
+2. Create manually in abapGit UI: https://<sap>/sap/bc/zabapgit
+
+### No Objects Found
+
+The package may be empty or objects not yet created:
+
+1. Verify package in SAP GUI: `SE21` → Display Package
+2. Ensure objects exist in the package
+
+## Full Workflow
+
+### Option 1: abapgit-agent (Recommended)
+
+```bash
+# Initialize
+abapgit-agent init --folder /abap --package ZMYPROJECT
+
+# Edit config
+vim .abapGitAgent
+
+# Create repository
+abapgit-agent create
+
+# Develop objects in ABAP...
+
+# Import objects to git
+abapgit-agent import
+
+# Pull to local folder
+git pull origin main
+```
+
+### Option 2: abapGit UI for Creation
+
+```bash
+# Initialize
+abapgit-agent init --folder /abap --package ZMYPROJECT
+
+# Edit config
+vim .abapGitAgent
+
+# Create repository in abapGit UI
+# https://<sap>/sap/bc/zabapgit → New → Online → Enter git URL
+
+# Develop objects in ABAP...
+
+# Import objects to git
+abapgit-agent import
+```
+
+## Related Commands
+
+- [`init`](init-command.md) - Initialize local configuration
+- [`create`](create-command.md) - Create online repository in ABAP
+- [`pull`](pull-command.md) - Pull and activate objects in ABAP

package/docs/init-command.md

@@ -0,0 +1,189 @@
+# init Command
+
+Initialize local configuration for an existing git repository.
+
+## Command
+
+```bash
+abapgit-agent init --folder /src/ --package ZMY_PACKAGE
+```
+
+## Prerequisite
+
+- Current folder is the root folder of a git repository
+- Git remote is configured (`git remote -v` returns a URL)
+
+## Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `--folder` | No | `/src/` | Subfolder path for ABAP source files |
+| `--package` | Yes | - | Target ABAP package |
+
+## Tasks
+
+### 1. Detect Git Remote URL
+
+```bash
+git remote get-url origin
+```
+
+- Fail if no remote configured
+
+### 2. Copy Configuration Template
+
+```bash
+cp .abapGitAgent.example .abapGitAgent
+```
+
+### 3. Update Configuration
+
+Add to `.abapGitAgent`:
+
+```json
+{
+  "package": "ZMY_PACKAGE",
+  "folder": "/src/"
+}
+```
+
+### 4. Create Folder
+
+```bash
+mkdir -p /src/
+```
+
+Add `.gitkeep` (optional):
+
+```bash
+touch /src/.gitkeep
+```
+
+### 5. Update .gitignore
+
+Add sensitive files to `.gitignore`:
+
+```
+.abapGitAgent
+.abapgit_agent_cookies.txt
+```
+
+### 6. Copy Documentation
+
+```bash
+cp /path/to/abapgit-agent/abap/CLAUDE.md .
+```
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `.abapGitAgent` | Configuration (user must edit host, user, password, gitUsername, gitPassword) |
+| `.gitignore` | Updated with sensitive files |
+| `CLAUDE.md` | ABAP coding guidelines |
+| `/src/` | Folder for ABAP source files |
+
+## .abapGitAgent Contents
+
+After `init` command, `.abapGitAgent` contains:
+
+```json
+{
+  "host": "your-sap-system.com",
+  "sapport": 443,
+  "client": "100",
+  "user": "TECH_USER",
+  "password": "your-password",
+  "language": "EN",
+  "gitUsername": "github-username",
+  "gitPassword": "github-token",
+  "referenceFolder": "~/abap-reference",
+  "package": "ZMY_PACKAGE",
+  "folder": "/src/"
+}
+```
+
+## GitHub Credentials
+
+For the `import` command to work, you need to configure GitHub credentials:
+
+1. Create a GitHub Personal Access Token (PAT):
+   - GitHub.com: https://github.com/settings/tokens
+
+2. Add to `.abapGitAgent`:
+
+```json
+{
+  "gitUsername": "<your-github-username>",
+  "gitPassword": "ghp_your_token_here"
+}
+```
+
+Or set environment variables:
+
+```bash
+export GIT_USERNAME="<your-github-username>"
+export GIT_PASSWORD="ghp_your_token_here"
+```
+
+## Post-Init Steps
+
+1. Edit `.abapGitAgent` with correct values:
+   - `host`: SAP system hostname
+   - `user`: SAP username
+   - `password`: SAP password
+   - `gitUsername`: GitHub username (for import command)
+   - `gitPassword`: GitHub PAT (for import command)
+
+2. Run `abapgit-agent create` to create abapGit repo in ABAP
+
+3. Run `abapgit-agent import` to import objects to git
+
+## Full Workflow
+
+```
+1. abapgit-agent init --folder /src/ --package ZMY_PACKAGE
+   └─> Creates .abapGitAgent, CLAUDE.md, /src/, updates .gitignore
+
+2. Edit .abapGitAgent (host, user, password, gitUsername, gitPassword)
+
+3. abapgit-agent create
+   └─> Creates online repository in ABAP
+
+4. abapgit-agent import
+   └─> Stages, commits, and pushes all objects from ZMY_PACKAGE
+
+5. git pull
+   └─> Optionally pull to local folder
+
+6. abapgit-agent pull
+   └─> Activate objects in ABAP
+```
+
+## Example
+
+```bash
+# Initialize
+abapgit-agent init --folder /abap/ --package ZMYPROJECT
+
+# Edit config
+vim .abapGitAgent
+
+# Create repo
+abapgit-agent create
+
+# Import objects to git
+abapgit-agent import
+
+# Pull to local folder
+git pull origin main
+
+# Activate in ABAP
+abapgit-agent pull
+```
+
+## Related Commands
+
+- [`create`](create-command.md) - Create online repository in ABAP
+- [`import`](import-command.md) - Import objects from package to git
+- [`pull`](pull-command.md) - Pull and activate objects in ABAP

package/docs/inspect-command.md

@@ -0,0 +1,158 @@
+# inspect Command Requirements
+
+## Overview
+
+Inspect ABAP source file(s) for syntax errors and issues.
+
+## Command
+
+```bash
+# Inspect single file
+abapgit-agent inspect --files zcl_my_class.clas.abap
+
+# Inspect multiple files
+abapgit-agent inspect --files zcl_my_class.clas.abap,zcl_other.clas.abap
+
+# With path
+abapgit-agent inspect --files abap/zcl_my_class.clas.abap
+```
+
+## Prerequisite
+
+- `.abapGitAgent` exists with valid credentials
+- Files must exist in the filesystem
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--files` | Yes | Comma-separated list of files to inspect |
+
+---
+
+## Tasks
+
+### 1. Validate Parameters
+
+- `--files` must be specified
+- Files must exist
+
+### 2. Load Configuration
+
+Read `.abapGitAgent` for credentials
+
+### 3. Fetch CSRF Token
+
+```bash
+GET /health (with X-CSRF-Token: fetch)
+```
+
+### 4. Make Inspect Request
+
+**Endpoint:** `POST /inspect`
+
+**Request Body:**
+```json
+{
+  "files": ["ZCL_MY_CLASS.CLASS.ABAP"]
+}
+```
+
+### 5. Display Results
+
+---
+
+## Output
+
+### Success (No Errors)
+
+```
+  Inspect for 1 file(s)
+
+  ✅ zcl_my_class.clas.abap - Syntax check passed (0 errors)
+```
+
+### With Errors
+
+```
+  Inspect for 1 file(s)
+
+  ❌ Syntax check failed (2 error(s)):
+
+  Errors:
+────────────────────────────────────────────────────────────
+  Line 15, Column 10:
+    "ZMYCLASS" is not a type
+
+  Line 20, Column 5:
+    Field "LV_VAR" is unknown
+```
+
+---
+
+## Response Structure
+
+```json
+{
+  "success": "X",
+  "object_type": "CLAS",
+  "object_name": "ZCL_MY_CLASS",
+  "error_count": 2,
+  "errors": [
+    {
+      "line": "15",
+      "column": "10",
+      "text": "\"ZMYCLASS\" is not a type",
+      "word": "ZMYCLASS"
+    }
+  ]
+}
+```
+
+---
+
+## Error Handling
+
+| Error | Message |
+|-------|---------|
+| File not found | `File not found: <path>` |
+| Invalid file format | `Invalid file format: <file>` |
+| No --files specified | `Error: --files parameter required` |
+
+---
+
+## File Format
+
+Same as pull command - files are parsed to extract object type and name:
+
+| File | Object Type | Object Name |
+|------|-------------|-------------|
+| `zcl_my_class.clas.abap` | CLAS | ZCL_MY_CLASS |
+| `zif_my_intf.intf.abap` | INTF | ZIF_MY_INTF |
+
+---
+
+## Example
+
+```bash
+# Syntax check
+abapgit-agent inspect --files zcl_my_class.clas.abap
+
+# Multiple files
+abapgit-agent inspect --files abap/zcl_my_class.clas.abap,abap/zcl_other.clas.abap
+```
+
+## Use Case
+
+Use `inspect` when:
+- Pull shows "Error updating where-used list" (syntax error)
+- You need detailed error messages with line numbers
+- Debugging activation failures
+
+```
+abapgit-agent pull
+   ❌ CLAS ZCL_MY_CLASS: Error updating where-used list
+
+abapgit-agent inspect --files abap/zcl_my_class.clas.abap
+   ❌ Line 15, Column 10: "ZMYCLASS" is not a type
+```