funifier-mcp 0.3.9 → 0.3.11

package/dist/mcp/tools/permissions.test.js

@@ -0,0 +1,355 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const permissions_1 = require("./permissions");
+const _backup_1 = require("./_backup");
+// Every mutating action now writes a snapshot to backupRoot(); redirect it to a temp dir
+// (via the FUNIFIER_BACKUP_ROOT seam) so tests never touch the real working tree.
+let backupDir;
+(0, vitest_1.beforeEach)(() => {
+    backupDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "funifier-perm-test-"));
+    process.env.FUNIFIER_BACKUP_ROOT = backupDir;
+});
+(0, vitest_1.afterEach)(() => {
+    delete process.env.FUNIFIER_BACKUP_ROOT;
+    fs_1.default.rmSync(backupDir, { recursive: true, force: true });
+});
+function readNewestSnapshot() {
+    const items = (0, _backup_1.listSnapshots)(backupDir);
+    if (items.length === 0)
+        throw new Error("no snapshot written");
+    return JSON.parse(fs_1.default.readFileSync(items[0].path, "utf8"));
+}
+const SECURITY = {
+    _id: "game1",
+    apps: [{ name: "Default", app_secret: "old-secret", scope: "read_all" }],
+    roles: [{ name: "player", timeout: "1d", scope: "read_all,write_actionlog" }],
+};
+function fakeApi(overrides = {}) {
+    const roles = [
+        { _id: "r1", name: "Admin", type: "system", item: "system", permissions: [] },
+        { _id: "r2", name: "Game Editor", type: "gamification", item: "game1", permissions: [] },
+    ];
+    const assignments = [{ type: "user", item: "u1", role: "r1" }];
+    return {
+        queryCollection: vitest_1.vi.fn().mockResolvedValue([structuredClone(SECURITY)]),
+        updateDocument: vitest_1.vi.fn().mockImplementation((_collection, doc) => Promise.resolve(doc)),
+        listRoles: vitest_1.vi.fn().mockResolvedValue(roles),
+        listRolesStrict: vitest_1.vi.fn().mockResolvedValue(roles),
+        getRoleById: vitest_1.vi.fn().mockResolvedValue({ _id: "r1", name: "Admin", type: "system", item: "system", permissions: [] }),
+        saveRole: vitest_1.vi.fn().mockImplementation((role) => Promise.resolve({ ...role, _id: role._id ?? "new-role" })),
+        deleteRole: vitest_1.vi.fn().mockResolvedValue({ ok: 1 }),
+        listRoleAssignments: vitest_1.vi.fn().mockResolvedValue(assignments),
+        listRoleAssignmentsStrict: vitest_1.vi.fn().mockResolvedValue(assignments),
+        assignRole: vitest_1.vi.fn().mockImplementation((payload) => Promise.resolve(payload)),
+        unassignRole: vitest_1.vi.fn().mockResolvedValue({ ok: 1 }),
+        ...overrides,
+    };
+}
+function makeInvoke(overrides = {}, connection = { serverUrl: "https://test.funifier.com" }) {
+    const api = fakeApi(overrides);
+    const holder = {
+        requireClient: () => api,
+        getConnectionInfo: () => ({
+            connected: true,
+            serverUrl: connection.serverUrl ?? null,
+            name: null,
+        }),
+    };
+    let handler;
+    const server = {
+        registerTool: (_name, _config, h) => { handler = h; },
+    };
+    (0, permissions_1.registerPermissionsTool)(server, holder);
+    return { invoke: (args) => handler(args), api };
+}
+(0, vitest_1.describe)("funifier_permissions", () => {
+    (0, vitest_1.it)("lists API applications from the security document", async () => {
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({ action: "list_api_apps" });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.queryCollection).toHaveBeenCalledWith("security", {}, { limit: 1, skip: 0 });
+        (0, vitest_1.expect)(result.content[0].text).toContain("old-…cret");
+        (0, vitest_1.expect)(result.content[0].text).not.toContain("old-secret");
+    });
+    (0, vitest_1.it)("upserts an API app by app_secret", async () => {
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({
+            action: "save_api_app",
+            data: JSON.stringify({ name: "Default Updated", app_secret: "old-secret", scope: "read_all,write_all" }),
+        });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.updateDocument).toHaveBeenCalledWith("security", vitest_1.expect.objectContaining({
+            apps: [{ name: "Default Updated", app_secret: "old-secret", scope: "read_all,write_all" }],
+        }));
+    });
+    (0, vitest_1.it)("removes a security role by name", async () => {
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({ action: "delete_security_role", name: "player" });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.updateDocument).toHaveBeenCalledWith("security", vitest_1.expect.objectContaining({ roles: [] }));
+    });
+    (0, vitest_1.it)("filters Studio roles by type and item", async () => {
+        const { invoke } = makeInvoke();
+        const result = await invoke({ action: "list_studio_roles", role_type: "gamification", item: "game1" });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(result.content[0].text).toContain("Game Editor");
+        (0, vitest_1.expect)(result.content[0].text).not.toContain("Admin");
+    });
+    (0, vitest_1.it)("saves a Studio role with permissions", async () => {
+        const { invoke, api } = makeInvoke();
+        const role = {
+            name: "Editor",
+            type: "gamification",
+            item: "game1",
+            permissions: [{ type: "page", object: "/studio/security", operations: { read: true, update: true } }],
+        };
+        const result = await invoke({ action: "save_studio_role", data: JSON.stringify(role) });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.saveRole).toHaveBeenCalledWith(role);
+    });
+    (0, vitest_1.it)("assigns a Studio role using individual fields", async () => {
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({
+            action: "assign_studio_role",
+            principal_type: "user",
+            principal_item: "u1",
+            role_id: "r1",
+        });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.assignRole).toHaveBeenCalledWith({ type: "user", item: "u1", role: "r1" });
+    });
+    (0, vitest_1.it)("returns isError for invalid JSON payloads", async () => {
+        const { invoke } = makeInvoke();
+        const result = await invoke({ action: "save_api_app", data: "not-json" });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain("Error in funifier_permissions");
+    });
+});
+(0, vitest_1.describe)("funifier_permissions native pre-write backup (no LLM in the loop)", () => {
+    (0, vitest_1.it)("writes a snapshot of the prior security doc BEFORE the mutation fires", async () => {
+        // The mutation mock records how many snapshots exist at the moment it is invoked.
+        let snapshotsWhenMutated = -1;
+        const { invoke, api } = makeInvoke({
+            updateDocument: vitest_1.vi.fn().mockImplementation((_collection, doc) => {
+                snapshotsWhenMutated = (0, _backup_1.listSnapshots)(backupDir).length;
+                return Promise.resolve(doc);
+            }),
+        });
+        // A genuinely new app, so the mutated doc (2 apps) differs from the prior doc (1 app).
+        const result = await invoke({
+            action: "save_api_app",
+            data: JSON.stringify({ name: "New App", app_secret: "brand-new", scope: "read_all" }),
+        });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.updateDocument).toHaveBeenCalled();
+        (0, vitest_1.expect)(snapshotsWhenMutated).toBe(1); // backup existed before updateDocument ran
+        const snap = readNewestSnapshot();
+        (0, vitest_1.expect)(snap.category).toBe("security");
+        (0, vitest_1.expect)(snap.existedBefore).toBe(true);
+        (0, vitest_1.expect)(snap.preImage).toEqual(SECURITY); // whole PRIOR doc, not the mutated 2-app version
+    });
+    (0, vitest_1.it)("aborts the mutation and returns isError when the backup write fails", async () => {
+        // Point the backup root at a path blocked by a file → mkdir for the category dir throws.
+        const blocker = path_1.default.join(backupDir, "blocker");
+        fs_1.default.writeFileSync(blocker, "not-a-directory");
+        process.env.FUNIFIER_BACKUP_ROOT = path_1.default.join(blocker, "nested");
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({
+            action: "save_api_app",
+            data: JSON.stringify({ name: "Default", app_secret: "old-secret", scope: "read_all" }),
+        });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain("Backup write failed (mutation aborted)");
+        (0, vitest_1.expect)(api.updateDocument).not.toHaveBeenCalled(); // the literal "native, not LLM" guarantee
+    });
+    (0, vitest_1.it)("records existedBefore=false / preImage=null when creating a brand-new studio role", async () => {
+        const { invoke, api } = makeInvoke();
+        const role = {
+            name: "Brand New",
+            type: "gamification",
+            item: "game1",
+            permissions: [{ type: "page", object: "/x", operations: { read: true } }],
+        };
+        const result = await invoke({ action: "save_studio_role", data: JSON.stringify(role) });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.saveRole).toHaveBeenCalledWith(role);
+        const snap = readNewestSnapshot(); // built by a real captureBackup, not a hand-faked fixture
+        (0, vitest_1.expect)(snap.category).toBe("studio-role");
+        (0, vitest_1.expect)(snap.existedBefore).toBe(false);
+        (0, vitest_1.expect)(snap.preImage).toBeNull();
+        (0, vitest_1.expect)(snap.naturalKey).toEqual({ name: "Brand New", type: "gamification", item: "game1" });
+    });
+    vitest_1.it.each([
+        ["save_api_app", { data: JSON.stringify({ name: "X", app_secret: "s", scope: "read_all" }) }],
+        ["delete_api_app", { app_secret: "old-secret" }],
+        ["save_security_role", { data: JSON.stringify({ name: "X", timeout: "1d", scope: "read_all" }) }],
+        ["delete_security_role", { name: "player" }],
+        ["save_studio_role", { data: JSON.stringify({ name: "X", type: "system", item: "system", permissions: [] }) }],
+        ["delete_studio_role", { role_id: "r1" }],
+        ["assign_studio_role", { principal_type: "user", principal_item: "u1", role_id: "r1" }],
+        ["unassign_studio_role", { principal_type: "user", principal_item: "u1", role_id: "r1" }],
+    ])("%s writes exactly one pre-write snapshot", async (action, args) => {
+        const { invoke } = makeInvoke();
+        const result = await invoke({ action, ...args });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)((0, _backup_1.listSnapshots)(backupDir).length).toBe(1);
+    });
+    (0, vitest_1.it)("restore_backup reapplies a security snapshot via updateDocument", async () => {
+        // 1. A real mutation captures the prior security doc.
+        const writer = makeInvoke();
+        await writer.invoke({
+            action: "save_api_app",
+            data: JSON.stringify({ name: "Default", app_secret: "old-secret", scope: "read_all" }),
+        });
+        (0, vitest_1.expect)((0, _backup_1.listSnapshots)(backupDir).length).toBe(1);
+        const backupPath = (0, _backup_1.listSnapshots)(backupDir)[0].path;
+        // 2. A fresh handler restores it — restore writes its own pre-write backup (BKP-11).
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({ action: "restore_backup", backup_path: backupPath });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.updateDocument).toHaveBeenCalledWith("security", vitest_1.expect.objectContaining({ _id: "game1" }));
+        (0, vitest_1.expect)((0, _backup_1.listSnapshots)(backupDir).length).toBe(2);
+    });
+    (0, vitest_1.it)("restore_backup rejects cross-server snapshots when serverUrl differs", async () => {
+        const writer = makeInvoke({}, { serverUrl: "https://tenant-a.funifier.com" });
+        await writer.invoke({
+            action: "save_api_app",
+            data: JSON.stringify({ name: "Default", app_secret: "old-secret", scope: "read_all" }),
+        });
+        const backupPath = (0, _backup_1.listSnapshots)(backupDir)[0].path;
+        const { invoke, api } = makeInvoke({}, { serverUrl: "https://tenant-b.funifier.com" });
+        const result = await invoke({ action: "restore_backup", backup_path: backupPath });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toMatch(/serverUrl mismatch/i);
+        (0, vitest_1.expect)(api.updateDocument).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.it)("delete_studio_role aborts when getRoleById fails to read the role", async () => {
+        const { invoke, api } = makeInvoke({
+            getRoleById: vitest_1.vi.fn().mockResolvedValue(undefined),
+        });
+        const result = await invoke({ action: "delete_studio_role", role_id: "r1" });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain("not found or unreadable");
+        (0, vitest_1.expect)(api.deleteRole).not.toHaveBeenCalled();
+        (0, vitest_1.expect)((0, _backup_1.listSnapshots)(backupDir).length).toBe(0);
+    });
+    (0, vitest_1.it)("save_studio_role aborts when listRolesStrict fails (avoids false absent snapshot)", async () => {
+        const { invoke, api } = makeInvoke({
+            listRolesStrict: vitest_1.vi.fn().mockRejectedValue(new Error("network down")),
+        });
+        const result = await invoke({
+            action: "save_studio_role",
+            data: JSON.stringify({
+                name: "Editor",
+                type: "gamification",
+                item: "game1",
+                permissions: [{ type: "page", object: "/x", operations: { read: true } }],
+            }),
+        });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain("Failed to capture pre-image");
+        (0, vitest_1.expect)(api.saveRole).not.toHaveBeenCalled();
+        (0, vitest_1.expect)((0, _backup_1.listSnapshots)(backupDir).length).toBe(0);
+    });
+    (0, vitest_1.it)("assign_studio_role aborts when listRoleAssignmentsStrict fails (avoids false absent snapshot)", async () => {
+        const { invoke, api } = makeInvoke({
+            listRoleAssignmentsStrict: vitest_1.vi.fn().mockRejectedValue(new Error("network down")),
+        });
+        const result = await invoke({
+            action: "assign_studio_role",
+            principal_type: "user",
+            principal_item: "u1",
+            role_id: "r1",
+        });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain("Failed to capture pre-image");
+        (0, vitest_1.expect)(api.assignRole).not.toHaveBeenCalled();
+        (0, vitest_1.expect)((0, _backup_1.listSnapshots)(backupDir).length).toBe(0);
+    });
+    (0, vitest_1.it)("restore_backup of an absent studio role resolves the _id via natural key and deletes it", async () => {
+        // 1. Create-path snapshot from a real save of a role absent in listRoles → existedBefore=false.
+        const writer = makeInvoke();
+        await writer.invoke({
+            action: "save_studio_role",
+            data: JSON.stringify({
+                name: "Brand New",
+                type: "gamification",
+                item: "game1",
+                permissions: [{ type: "page", object: "/x", operations: { read: true } }],
+            }),
+        });
+        const backupPath = (0, _backup_1.listSnapshots)(backupDir)[0].path;
+        // 2. At restore time the role now exists with a server-assigned _id.
+        const { invoke, api } = makeInvoke({
+            listRoles: vitest_1.vi.fn().mockResolvedValue([
+                { _id: "created-id", name: "Brand New", type: "gamification", item: "game1", permissions: [] },
+            ]),
+        });
+        const result = await invoke({ action: "restore_backup", backup_path: backupPath });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(api.deleteRole).toHaveBeenCalledWith("created-id");
+    });
+    (0, vitest_1.it)("restore_backup with a missing path errors and performs no remote write", async () => {
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({ action: "restore_backup", backup_path: path_1.default.join(backupDir, "missing.json") });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(api.updateDocument).not.toHaveBeenCalled();
+        (0, vitest_1.expect)(api.deleteRole).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.it)("restore_backup rejects path traversal outside the backup root", async () => {
+        const outside = path_1.default.join(backupDir, "..", "outside-backup.json");
+        fs_1.default.writeFileSync(outside, JSON.stringify({
+            version: 1,
+            action: "save_api_app",
+            category: "security",
+            resourceId: "game1",
+            existedBefore: true,
+            capturedAt: "2026-05-28T14:31:02.123Z",
+            serverUrl: null,
+            preImage: SECURITY,
+        }));
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({ action: "restore_backup", backup_path: outside });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toMatch(/must be within/i);
+        (0, vitest_1.expect)(api.updateDocument).not.toHaveBeenCalled();
+        fs_1.default.rmSync(outside, { force: true });
+    });
+    (0, vitest_1.it)("restore_backup errors when a studio-role snapshot lacks naturalKey", async () => {
+        const badPath = path_1.default.join(backupDir, "studio-role", "missing-key.json");
+        fs_1.default.mkdirSync(path_1.default.dirname(badPath), { recursive: true });
+        fs_1.default.writeFileSync(badPath, JSON.stringify({
+            version: 1,
+            action: "save_studio_role",
+            category: "studio-role",
+            resourceId: "r1",
+            existedBefore: false,
+            capturedAt: "2026-05-28T14:31:02.123Z",
+            serverUrl: null,
+            preImage: null,
+        }));
+        const { invoke, api } = makeInvoke();
+        const result = await invoke({ action: "restore_backup", backup_path: badPath });
+        (0, vitest_1.expect)(result.isError).toBe(true);
+        (0, vitest_1.expect)(result.content[0].text).toContain("Studio-role snapshot missing naturalKey");
+        (0, vitest_1.expect)(api.saveRole).not.toHaveBeenCalled();
+        (0, vitest_1.expect)(api.deleteRole).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.it)("list_backups returns captured snapshots newest-first", async () => {
+        const writer = makeInvoke();
+        await writer.invoke({ action: "delete_security_role", name: "player" });
+        const { invoke } = makeInvoke();
+        const result = await invoke({ action: "list_backups" });
+        (0, vitest_1.expect)(result.isError).toBeUndefined();
+        (0, vitest_1.expect)(result.content[0].text).toContain("Backups (1)");
+        (0, vitest_1.expect)(result.content[0].text).toContain("security");
+    });
+});
+//# sourceMappingURL=permissions.test.js.map

package/dist/mcp/tools/permissions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.test.js","sourceRoot":"","sources":["../../../src/mcp/tools/permissions.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "funifier-mcp",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "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",
@@ -72,4 +72,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/skills/funifier/SKILL.md

@@ -36,6 +36,7 @@ Then read a result with `funifier_read_doc path=<path>`.
 | Create a Funifier trigger — guided workflow from entity/event selection to Groovy code generation | `references/create-trigger.md` |
 | Create a Funifier scheduler — guided workflow from naming and cron expression to Groovy code generation | `references/create-scheduler.md` |
 | Create a Funifier prepared aggregate — guided workflow for building MongoDB aggregate pipelines for reports and dashboards | `references/create-aggregate.md` |
+| Create, edit, or query Date fields safely via REST, funifier_database, triggers, schedulers, aggregate, and prepared aggregate; use whenever a payload or filter contains dates | `references/date-handling.md` |
 | Create a Funifier challenge — missions with action rules and point rewards | `references/create-challenge.md` |
 | Create a Funifier action — define trackable player behaviors with attributes | `references/create-action.md` |
 | Create a Funifier point category — XP, coins, or custom metrics | `references/create-point.md` |

package/skills/funifier/references/configure-security.md

@@ -94,3 +94,21 @@ GET /v3/database/security/<API_KEY>?strict=true
 ```
 
 Teste login de jogador e confirme que o token retornado tem os scopes corretos.
+
+### 7. Backup automático e rollback (funifier_permissions)
+
+Toda mutação via `funifier_permissions` grava um snapshot completo em `.funifier/backups/` **antes** da escrita remota. Snapshots podem conter `app_secret` e escopos — mantenha `.funifier/backups/` no `.gitignore` (o `init` adiciona automaticamente).
+
+**Listar backups:**
+```
+funifier_permissions action=list_backups
+```
+
+**Restaurar (rollback):**
+```
+funifier_permissions action=restore_backup backup_path=<path retornado por list_backups>
+```
+
+O restore valida que o `serverUrl` do snapshot coincide com a conexão atual — não aplique backup de outro tenant. O próprio restore também gera um snapshot prévio, permitindo desfazer o rollback.
+
+Variáveis opcionais: `FUNIFIER_PROJECT_ROOT` (diretório do projeto; definida nos configs gerados pelo `init`) e `FUNIFIER_BACKUP_ROOT` (substitui `.funifier/backups/` por outro diretório). Snapshots não expiram automaticamente — remova arquivos antigos manualmente quando necessário.

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

@@ -74,8 +74,12 @@ If search returns insufficient results, read these directly:
 | `point_category` | Tipos de ponto — `_id`, `category`, `shortName` |
 | `catalog_item` | Loja virtual — `_id`, `catalogId`, `name`, `requires` |
 
+Se o pipeline filtrar ou criar campos de data, leia também `references/date-handling.md` antes de montar o payload.
+
 ### Expressões de data Funifier
 
+Para regras completas de criação/edição/consulta de datas via REST, triggers, schedulers, aggregate e prepared aggregate, leia `references/date-handling.md`.
+
 | Expressão | Significado |
 |---|---|
 | `{"$date": "-0d-"}` | Início do dia atual |
@@ -84,6 +88,8 @@ If search returns insufficient results, read these directly:
 | `{"$date": "-0y-"}` | Início do ano atual |
 | `{"$date": "-1d-"}` | Início do dia anterior |
 
+**Importante:** em aggregate direto e prepared aggregate, prefira expressões relativas Funifier dentro de `$date` (`-0M-`, `-0M+`) ou timestamps em milissegundos para datas absolutas. Para datas absolutas parametrizadas em prepared aggregate, normalize no `script` com `DateUtil.parse(...)` e substitua diretamente em `$gte`/`$lte`.
+
 ---
 
 ## Steps

package/skills/funifier/references/date-handling.md

@@ -0,0 +1,172 @@
+# funifier-date-handling
+
+Create, edit, or query Date fields safely via REST, funifier_database, triggers, schedulers, aggregate, and prepared aggregate; use whenever a payload or filter contains dates
+
+---
+
+## 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 "date dates bson extended-json aggregate prepared DateUtil strict timestamp timezone"
+```
+
+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/database-access`
+- `funifier_read_doc path=guides/aggregates`
+- `funifier_read_doc path=modules/database`
+
+## Steps
+
+## Regra de ouro
+
+Use **BSON Extended JSON** para persistir datas em objetos customizados:
+
+```json
+{
+  "startsAt": { "$date": "2026-05-28T13:30:00.000Z" },
+  "created": { "$date": "2026-05-28T13:30:00.000Z" }
+}
+```
+
+Evite salvar data como string ISO solta quando o campo será filtrado como data. String não compara corretamente com BSON Date em consultas Mongo.
+
+---
+
+## Criar/editar datas via REST ou funifier_database
+
+- Gere datas em UTC (`toISOString()` no JavaScript).
+- Ao criar/editar documentos, envie campos de data como `{ "$date": "<ISO UTC>" }`.
+- Em updates via `PUT /v3/database/<collection>`, reenvie o documento completo: o endpoint faz **full replace**.
+- Use `strict=true` ao ler quando precisar confirmar tipos BSON preservados na resposta.
+
+```json
+{
+  "_id": "cycle_2026_05",
+  "name": "Ciclo Maio",
+  "startsAt": { "$date": "2026-05-01T00:00:00.000Z" },
+  "endsAt": { "$date": "2026-05-31T23:59:59.999Z" }
+}
+```
+
+Não salve assim se o campo será filtrado como data:
+
+```json
+{ "startsAt": "2026-05-01T00:00:00.000Z" }
+```
+
+---
+
+## Triggers e schedulers
+
+Scripts Groovy de triggers, schedulers e prepared aggregates já importam `DateUtil` e `JsonUtil` nos runners. Se o script precisa calcular/comparar datas, normalize explicitamente com `DateUtil.parse(...)`, `new Date()` ou `DateUtil.fromKeyword(...)`.
+
+```groovy
+void trigger(event, entity, player, database) {
+  entity.createdAt = new Date()
+  entity.startsAt = DateUtil.parse('2026-05-01T00:00:00.000Z')
+  entity.endsAt = DateUtil.fromKeyword('+7d+')
+}
+```
+
+---
+
+## Aggregate direto
+
+Prefira períodos relativos com `$date`, que passam pelo `FunifierMarshaller` e são convertidos por `DateUtil.fromKeyword`:
+
+```json
+[
+  {
+    "$match": {
+      "time": {
+        "$gte": { "$date": "-0M-" },
+        "$lte": { "$date": "-0M+" }
+      }
+    }
+  }
+]
+```
+
+Não generalize para `q` de GET/list/count/delete: esses caminhos montam a query string diretamente.
+
+Para data absoluta em aggregate direto, prefira timestamp em milissegundos dentro de `$date` ou teste o formato na instância antes de documentar como padrão.
+
+---
+
+## Prepared aggregate (`/v3/find/<id>`)
+
+Regras extras:
+
+1. O campo `aggregate` salvo no recurso é uma **string JSON serializada**, não array nativo.
+2. Parâmetros só são substituídos quando aparecem como string literal `"$param:nome"`.
+
+Para datas relativas, use parâmetros dentro de `$date` (`"$date":"$param:start"`) e preencha `params.start` com keywords como `-0M-`.
+
+Para datas absolutas, normalize no `script` para `Date` e substitua diretamente em `$gte`/`$lte`:
+
+```json
+{
+  "aggregate": "[{"$match":{"soldAt":{"$gte":"$param:start","$lte":"$param:end"}}}]",
+  "script": "void prepare(aggregations, params) {\n  Date start = params.startIso ? DateUtil.parse(params.startIso) : DateUtil.fromKeyword('-0M-')\n  Date end = params.endIso ? DateUtil.parse(params.endIso) : DateUtil.fromKeyword('-0M+')\n  if (start == null || end == null) throw new IllegalArgumentException('Invalid date params')\n  params.put('start', start)\n  params.put('end', end)\n}\n"
+}
+```
+
+Não coloque o parâmetro convertido para `Date` dentro de `{ "$date": "$param:start" }`.
+
+---
+
+## Checklist
+
+- [ ] Salvar Date como `{ "$date": "<ISO UTC>" }`, nunca string solta.
+- [ ] Preservar todos os campos em `PUT`.
+- [ ] Usar keywords Funifier (`-0d-`, `-0M-`, `-0M+`, `+1d+`) apenas em caminhos que passam pelo `FunifierMarshaller`.
+- [ ] Em prepared aggregate, salvar `aggregate` como string JSON serializada.
+- [ ] Em prepared aggregate, usar `"$param:nome"` exatamente como string.
+- [ ] Para data absoluta em prepared aggregate, converter no `script` com `DateUtil.parse`, validar `null`, e substituir o `Date` diretamente em `$gte`/`$lte`.
+- [ ] Testar aggregate direto antes de salvar como prepared aggregate.

package/skills/funifier/references/debug.md

@@ -47,6 +47,8 @@ If search returns insufficient results, read these directly:
 | Challenge não avança | Action não existe ou operator/total errado | `funifier_list type=action search=<id>` |
 | Compra falha sem erro | Saldo insuficiente ou `requires` errado | Checar ponto do jogador: `GET /v3/player/<id>/status` |
 | `/v3/database` retorna vazio | Scope `database` ausente na role | Adicionar `database` ao scope via Security |
+| Filtro por data não encontra registros | Campo foi salvo como string ISO ou parâmetro ISO foi usado dentro de `$date` sem normalização | Salvar como `{ "$date": "<ISO UTC>" }`; em prepared aggregate converter ISO com `DateUtil.parse` no script |
+| Prepared aggregate com data absoluta falha/retorna vazio | `"$param:start"` dentro de `{ "$date": ... }` recebeu string ISO | Converter no `script` para `Date` e usar `"$gte":"$param:start"` diretamente |
 
 ---