funifier-mcp 0.3.19 → 0.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funifier-mcp",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "description": "Funifier AI toolkit — MCP server, API client, and Claude Code skills for the Funifier gamification platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/funifier/SKILL.md

@@ -70,6 +70,7 @@ Then read a result with `funifier_read_doc path=<path>`.
 | Upload files to Funifier — images and documents for player avatars, challenge resources, and visual assets; use when adding media to the platform, not for CSV data import (use funifier-import-csv) or static frontend hosting (use funifier-implement-frontend) | `references/upload-file.md` |
 | Create, list, and drop MongoDB single-field indexes on Funifier collections via the REST API. Composite (multi-field) indexes are NOT supported by this endpoint — see Limitation section. | `references/manage-indexes.md` |
 | Cross-check a project's Funifier API calls against the live security document — scan code for usage, build an evidence-backed manifest, run the deterministic audit engine, and report missing scopes, excess tokens, and static danger findings; use when debugging 401s, auditing minimum privilege, or verifying permissions before deploying; audit is read-only and never changes any configuration | `references/audit-permissions.md` |
+| Use the server-side utility classes from com.funifier.engine.util in Groovy triggers, schedulers, and public endpoints — validates CPF, encrypts fields with AES/BCrypt/PGP, renders Mustache templates, evaluates inline expressions, computes object diffs/changelogs, converts JSON, generates Excel, makes HTTP calls, and handles files and pagination | `references/server-utils.md` |
 
 ## Documented Modules
 

package/skills/funifier/references/create-trigger.md

@@ -65,19 +65,39 @@ If search returns insufficient results, read these directly:
 
 ## Steps
 
-## ⚠ Regra crítica: triggers não impedem persistência via throw
+## ⚠ Regra crítica: quando `throw` interrompe a operação
 
-O Funifier **sempre salva o documento** antes de executar o trigger.
+Há **dois modos**, e qual vale depende de onde a trigger roda:
 
-- `before_create` → enriquecimento apenas (normalizar, preencher defaults)
-- Rejeitar criação → usar `after_create`: validar → se inválido:
+- **Modo A — estrito (`throw` aborta):** SÓ em `before_create`/`before_update`/`before_delete` de **coleções de banco** via Database API (`POST`/`PUT`/`DELETE /v3/database/{collection}`). O `DatabaseRest` roda via `TriggerManager.executeStrict`: qualquer exceção aborta a operação — o documento não é gravado/removido e a API responde **HTTP 500** `{ "message": "<msg>", "statusCode": 500 }`. ⚠️ **Recurso version-dependent** — nem toda instância recebeu a atualização. **Sonde antes de depender** (ver bloco de detecção abaixo) ou use o Modo B.
+- **Modo B — persistência garantida (`throw` NÃO cancela):** todo o resto (player, action, swap, quiz, achievement pelos managers, eventos `after_*`, `*_bulk`/`csv_*`). O documento é salvo antes do trigger rodar. Rejeitar = `after_create`:
   ```java
-  database.delete(entity._id, "collection__c");
+  database.delete(entity.id, "collection__c");
   entity.clear();
   entity.put("message", "motivo");
   return;
   ```
-- Para lógica complexa, use `BusinessException` interna (capturada dentro do trigger, não propaga para a plataforma).
+  Para lógica complexa, use `BusinessException` interna (capturada dentro do trigger).
+
+**Regra de ouro:** se o suporte ao Modo A não for confirmado, **gere código no Modo B** e diga ao usuário que o Modo A exige instância atualizada. Detalhes e exemplos: `funifier_read_doc path=guides/triggers-guide` §8.
+
+## 🔎 Detectar suporte ao Modo A (sonda)
+
+Antes de entregar uma trigger que aborta via `throw`, confirme na instância conectada:
+
+```
+# 1. cria trigger-sonda que sempre lança exceção
+funifier_save type=trigger payload={"name":"__probe_strict_mode__","entity":"probe_strict__c","event":"before_create","active":true,"script":"void trigger(event, entity, player, database){ throw new RuntimeException(\"__STRICT_PROBE_BLOCKED__\"); }"}
+# 2. tenta inserir (passa por DatabaseRest.insert → executeStrict)
+funifier_database action=insert collection=probe_strict__c payload={"probe":true}
+#    → erro 500 com "__STRICT_PROBE_BLOCKED__"  = Modo A SUPORTADO
+#    → insert bem-sucedido                       = Modo A NÃO suportado (use Modo B)
+# 3. limpeza (sempre)
+funifier_database action=delete collection=probe_strict__c filter={"probe":true}
+funifier_delete type=trigger id=<_id da sonda>
+```
+
+Sem permissão de escrita / produção sensível → **assuma o Modo B** e avise o usuário.
 
 ---
 
@@ -129,8 +149,8 @@ Perguntar (ou inferir do contexto):
 | `achievement` | `before_create` | Enriquecer conquista com dados de origem (`context.extra`) |
 | `player` | `after_create` | Inicializar campos customizados ao criar jogador |
 | `player` | `before_update` | Normalizar campos antes de salvar atualização |
-| `custom__c` | `before_create` | Normalizar/enriquecer documento customizado |
-| `custom__c` | `after_create` | Validar e rejeitar se inválido (delete + message) |
+| `custom__c` | `before_create` | Normalizar/enriquecer documento; **rejeitar via `throw` no Modo A** (instância atualizada — sondar antes) |
+| `custom__c` | `after_create` | Validar e rejeitar se inválido (delete + message) — **portável, qualquer instância** |
 | `custom__c` | `after_bulk` | Processar import em lote (entity é uma List) |
 
 ### 2. Verificar se já existe
@@ -183,11 +203,3 @@ funifier_logs type=trigger id=<_id>
 ```
 
 Confirme que não há erros de compilação ou execução. Se houver, leia o stack trace e corrija o script.
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| Achievement constants TYPE_POINT=0, TYPE_CHALLENGE=1, TYPE_VIRTUAL_GOOD=2, TYPE_LEVEL=3 are defined in the Achievement class | ✓ verified | Class:src/main/java/com/funifier/engine/achievement/Achievement.java:Achievement |
-| ActionLog is the entity class for action triggers with fields actionId, userId, attributes (Map), time, and id | ✓ verified | Class:src/main/java/com/funifier/engine/action/ActionLog.java:ActionLog |
-| TriggerManager is the class that manages trigger script execution and lifecycle in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java:TriggerManager |

package/skills/funifier/references/debug.md

@@ -90,9 +90,3 @@ Leia o arquivo de doc específico para o módulo com problema:
 - Scheduler → `funifier_read_doc path=modules/scheduler`
 - Aggregate → `funifier_read_doc path=guides/aggregates`
 - Security/Auth → `funifier_read_doc path=modules/security`
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| TriggerManager is the entry point for trigger script execution and error capture in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/integration/trigger/TriggerManager.java:TriggerManager |

package/skills/funifier/references/help.md

@@ -79,9 +79,3 @@ Baseado na tabela acima, instrua o usuário a usar a skill específica.
 ### 4. Se não encontrar skill específica
 
 Consulte `funifier_read_doc path=index` e leia o módulo relevante diretamente.
-
-## Verified References
-
-| Claim | Status | Evidence |
-|-------|--------|----------|
-| Achievement is the core entity class representing all gamification rewards in funifier-service | ✓ verified | Class:src/main/java/com/funifier/engine/achievement/Achievement.java:Achievement |

package/skills/funifier/references/server-utils.md

@@ -0,0 +1,94 @@
+# funifier-server-utils
+
+Use the server-side utility classes from com.funifier.engine.util in Groovy triggers, schedulers, and public endpoints — validates CPF, encrypts fields with AES/BCrypt/PGP, renders Mustache templates, evaluates inline expressions, computes object diffs/changelogs, converts JSON, generates Excel, makes HTTP calls, and handles files and pagination
+
+---
+
+## Formato do payload (obrigatório)
+
+Funifier armazena código como **strings JSON escapadas**. Ao montar o payload do `funifier_save`:
+
+- **Quebra de linha** → `\n` (nunca newline literal dentro da string)
+- **Aspas duplas** dentro do código → `\"`
+- **Backslash** → `\\` (regex `\b` vira `\\b`; dentro de Groovy com string-building pode exigir `\\\\b`)
+- **Tab** → `\t` (se usar)
+- **Pipelines de aggregate** vão como **string JSON** (não objeto aninhado) — serialize o array inteiro
+
+A regra prática: monte o objeto em JavaScript normalmente e passe por `JSON.stringify` — o MCP faz isso automaticamente quando você entrega o payload como JSON. **Nunca** cole código multilinha cru no meio do JSON.
+
+### Exemplo 1 — custom-page (html + angularjs script)
+
+```json
+{
+  "title": "Ciclos",
+  "slug": "studio/custom/ciclos",
+  "html": "<div class=\"row\">\n  <div class=\"col-md-12\">\n    <h2>Ciclos</h2>\n  </div>\n</div>\n",
+  "script": "$scope.all = [];\n$scope.loading = false;\n\n$scope.list = function () {\n  $scope.loading = true;\n};\n$scope.list();\n"
+}
+```
+
+### Exemplo 2 — aggregate preparado (pipeline JSON + script Groovy)
+
+```json
+{
+  "_id": "extrato",
+  "title": "Extrato de Pontos",
+  "collection": "extrato",
+  "aggregate": "[\n  {\n    \"$match\": { \"player\": \"$param:player\" }\n  },\n  {\n    \"$sort\": { \"time\": -1 }\n  }\n]",
+  "script": "void prepare(aggregations, params) {\n    if (context.get(\"player\") != null) {\n        params.put(\"player\", context.get(\"player\"));\n    } else {\n        params.put(\"player\", \"NAO_EXISTE\");\n    }\n}\n"
+}
+```
+
+Note que `aggregate` é uma **string** contendo JSON serializado (com `\n` e `\"` escapados), **não** um array nativo. Mesma regra vale para `script` em triggers/schedulers/aggregates e `html`/`script` em custom-pages.
+
+---
+
+## Before starting — find relevant docs
+
+Use the `funifier_search_docs` MCP tool to load only what you need:
+
+```
+funifier_search_docs "cpf cnpj validar validate cpf-util aes encrypt decrypt criptografar criptografia bcrypt hash senha password pgp pgpcrypt rsa asymmetric totp otp 2fa qrcode google-authenticator mustache template render handlebars expression inline formula avaliar diff changelog auditoria comparar compare json serialize deserialize jsonutil excel xlsx spreadsheet planilha relatorio currency moeda formatar format http get post requisicao external url read-url pagination paginar paginacao paginate file stream arquivo util helper utility server-side groovy"
+```
+
+Then read the most relevant results with `funifier_read_doc path=<path>`.
+
+## Primary docs for this skill
+
+If search returns insufficient results, read these directly:
+
+- `funifier_read_doc path=guides/server-utils`
+- `funifier_read_doc path=guides/triggers-guide`
+- `funifier_read_doc path=guides/java-managers`
+
+## Steps
+
+### 1. Understand the requirement
+
+Ask the user what they want to create or accomplish. Gather:
+- The name/title
+- The purpose and behavior
+- Any specific configuration or constraints
+
+### 2. Search for relevant documentation
+
+Run the lexical search (command shown above) and read the returned files.
+
+### 3. Check existing resources (if MCP available)
+
+Use `funifier_list` with the relevant type and a `search` parameter to see
+if a similar resource already exists. Never list all resources without a search term.
+
+### 4. Design and confirm
+
+Based on the docs, outline the configuration to the user and confirm before saving.
+
+### 5. Create or update
+
+Use `funifier_save` with the appropriate type and a JSON payload to create or
+update the resource. If MCP is unavailable, show the complete JSON for manual use.
+
+### 6. Validate
+
+Use `funifier_logs` (for triggers/schedulers) or `funifier_get` to confirm
+the resource was saved correctly and executed without errors.