@netoalmanca/advpl-sensei 1.1.5 → 1.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netoalmanca/advpl-sensei",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "MCP Server for ADVPL/TLPP Protheus ecosystem",
   "main": "dist/index.js",
   "type": "module",

package/skills/advpl-code-generation/SKILL.md

@@ -19,7 +19,18 @@ Patterns and templates for generating clean, standardized ADVPL and TLPP code fo
 - Creating SOAP Web Services
 - Any new .prw or .tlpp file creation
 
+## Critical Rules (MANDATORY)
+
+1. **Anti-Hallucination**: Never use functions not found in the TDN or the local Function Registry (e.g., `HttpServer`).
+2. **ExecAuto vs RecLock**:
+   - **NEVER** use `RecLock` to create or update records in core business tables (SC5, SC6, SC7, SD1, SD2, SF1, SF2, SE1, SE2, SB1).
+   - **ALWAYS** use `MSExecAuto` (e.g., `MATA410` for Sales Orders) for these entities to ensure field validation, triggers, and data integrity.
+   - Refer to `patterns-execauto.md` for implementation details.
+3. **Variable Scope**: Always use `Local`. Never use `Public`. Avoid `Private` except for ExecAuto control variables (`lMsErroAuto`).
+4. **Hungarian Notation**: Strictly follow the naming conventions below.
+
 ## Naming Conventions
+... (rest of the file)
 
 | Element | Convention | Example |
 |---------|-----------|---------|

package/skills/advpl-code-generation/patterns-execauto.md

@@ -0,0 +1,116 @@
+# Protheus ExecAuto Patterns
+
+Manual for implementing automated routines (ExecAuto) in TOTVS Protheus. This is the **mandatory** pattern for complex business entities like Sales Orders, Purchase Orders, and Invoices.
+
+---
+
+## 1. Why use ExecAuto?
+
+Directly using `RecLock` on core tables (SC5, SC6, SC7, SD1, SD2, etc.) bypasses:
+- **Field Validations** (VLDUSER, CNIVEL, etc.)
+- **Automatic Triggers** (SX7)
+- **Integrity Checks** (SX9)
+- **Standard Business Rules** (Calculations, stock updates, financial entries)
+
+**MANDATORY:** Always use `MSExecAuto` for entities that have a standard Protheus routine.
+
+---
+
+## 2. Sales Order (MATA410)
+
+The most common ExecAuto. It handles header (SC5) and items (SC6) simultaneously.
+
+### 2.1 Basic Structure
+
+```advpl
+#Include "TOTVS.CH"
+
+/*/{Protheus.doc} MySalesOrder
+Example of Sales Order creation via ExecAuto
+@type function
+/*/
+User Function MySalesOrder(oRequest)
+    Local aCabec     := {}
+    Local aItens     := {}
+    Local aLinha     := {}
+    Local i          := 0
+    Local lOk        := .T.
+    
+    // MSExecAuto global control variables
+    Private lMsErroAuto := .F.
+    Private lMsHelpAuto := .T.
+
+    // 1. Prepare Header (SC5)
+    // Format: { FieldName, Value, Nil }
+    aAdd(aCabec, {"C5_TIPO",    "N",               Nil})
+    aAdd(aCabec, {"C5_CLIENTE", oRequest["client"], Nil})
+    aAdd(aCabec, {"C5_LOJACLI", oRequest["store"],  Nil})
+    aAdd(aCabec, {"C5_CONDPAG", "001",             Nil})
+    aAdd(aCabec, {"C5_TABELA",  "01",              Nil})
+    aAdd(aCabec, {"C5_EMISSAO", dDataBase,         Nil})
+
+    // 2. Prepare Items (SC6)
+    // Format: Array of arrays, where each inner array is a line
+    For i := 1 To Len(oRequest["items"])
+        aLinha := {}
+        aAdd(aLinha, {"C6_ITEM",    StrZero(i, 2), Nil})
+        aAdd(aLinha, {"C6_PRODUTO", oRequest["items"][i]["product"], Nil})
+        aAdd(aLinha, {"C6_QTD",     oRequest["items"][i]["quantity"], Nil})
+        aAdd(aLinha, {"C6_PRECO",   oRequest["items"][i]["price"], Nil})
+        aAdd(aLinha, {"C6_TES",     "501", Nil})
+        aAdd(aItens, aLinha)
+    Next i
+
+    // 3. Execute MATA410 (3 = Inclusion, 4 = Alteration, 5 = Deletion)
+    MSExecAuto({|x,y,z| MATA410(x,y,z)}, aCabec, aItens, 3)
+
+    // 4. Handle Errors
+    If lMsErroAuto
+        lOk := .F.
+        Conout("Error in MATA410 ExecAuto")
+        MostraErro() // Log or show errors
+    Else
+        Conout("Sales Order created: " + SC5->C5_NUM)
+    EndIf
+
+Return lOk
+```
+
+---
+
+## 3. Operations Reference
+
+| Operation | Value | Description |
+|-----------|-------|-------------|
+| Inclusion | 3 | Create new record |
+| Alteration | 4 | Update existing record (requires positioning) |
+| Deletion | 5 | Remove record (requires positioning) |
+
+---
+
+## 4. Error Handling Pattern for APIs
+
+When using ExecAuto inside a REST API, you should capture the error log into a string to return in the JSON response.
+
+```advpl
+If lMsErroAuto
+    cError := GetAutoGRLog() // Captures the error log
+    SetRestFault(500, cError)
+EndIf
+```
+
+---
+
+## 5. Common ExecAuto Routines
+
+| Entity | Routine | Table |
+|--------|---------|-------|
+| Sales Order | `MATA410` | SC5/SC6 |
+| Purchase Order | `MATA120` | SC7 |
+| Products | `MATA010` | SB1 |
+| Customers | `CRMA980` | SA1 |
+| Invoices (Inbound) | `MATA103` | SF1/SD1 |
+| Invoices (Outbound) | `MATA461` | SF2/SD2 |
+| Inventory Adjustments | `MATA241` | SD3 |
+| Accounts Payable | `FINA050` | SE2 |
+| Accounts Receivable | `FINA040` | SE1 |

package/skills/advpl-code-generation/patterns-rest.md

@@ -97,11 +97,13 @@ WsMethod GET WsReceive nPage, nPageSize WsService CUSTOMERS
 
 Return lRet
 ```
-
 ### 1.3 POST Method - Create
 
+**IMPORTANT:** While the example below uses `RecLock` for simple entities like `SA1`, you MUST use `MSExecAuto` for complex business entities (Sales Orders, Purchase Orders, Invoices). Refer to `patterns-execauto.md` for details.
+
 ```advpl
 WsMethod POST WsService CUSTOMERS
+```
     Local lRet     := .T.
     Local oJson    := JsonObject():New()
     Local oResp    := Nil