@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/test-tools.js

@@ -0,0 +1,388 @@
+/**
+ * Test tools: test.assert
+ *
+ * Entity state assertion with optional polling for agentic verify loops.
+ */
+import { z } from "zod";
+import { ToolError } from "./errors.js";
+import { getEntityMeta, SUPPORTED_ENTITY_TYPES } from "./entity-registry.js";
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+export const TestAssertInputSchema = z.object({
+    entityType: z.string().min(1),
+    id: z.string().optional().describe("Entity ID (preferred)"),
+    ref: z.string().optional().describe("Entity ref (fallback)"),
+    assertions: z.object({
+        status: z.string().optional().describe("Expected entity status"),
+        type: z.string().optional().describe("Expected entity type"),
+        subtype: z.string().optional().describe("Expected entity subtype"),
+        attributes: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Expected attribute key-value pairs"),
+        edges: z
+            .record(z.string(), z.object({
+            minCount: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Minimum expected edge count"),
+            maxCount: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Maximum expected edge count"),
+            status: z
+                .string()
+                .optional()
+                .describe("Expected status on related entities"),
+        }))
+            .optional()
+            .describe("Assertions on related entity edges"),
+    }),
+    poll: z
+        .boolean()
+        .default(false)
+        .describe("If true, retry assertions until they pass or timeout."),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(300000)
+        .default(60000)
+        .describe("Polling timeout in ms (default: 60000)."),
+    intervalMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(30000)
+        .default(5000)
+        .describe("Polling interval in ms (default: 5000)."),
+});
+// ---------------------------------------------------------------------------
+// Tool definitions (JSON Schema for MCP)
+// ---------------------------------------------------------------------------
+export const TEST_TOOL_DEFINITIONS = [
+    {
+        name: "test.assert",
+        description: [
+            "Assert entity state matches expectations with optional polling.",
+            "",
+            "Deep assertion on entity fields, attributes, and edge counts/statuses.",
+            "Human-readable failure messages.",
+            "",
+            "POLLING MODE: Set poll=true to retry until assertions pass or timeout.",
+            "Useful after sending events when state changes are async.",
+            "",
+            "ASSERTIONS:",
+            "- status: exact match on entity status",
+            "- type: exact match on entity type",
+            "- subtype: exact match on entity subtype",
+            "- attributes: key-value pairs that must be present on the entity",
+            "- edges: min/max count and status on related entities",
+            "",
+            "EXAMPLE: Assert order is BOOKED with at least 1 fulfilment:",
+            '{ entityType: "ORDER", ref: "HD-001", assertions: { status: "BOOKED", edges: { fulfilments: { minCount: 1 } } } }',
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                entityType: {
+                    type: "string",
+                    description: "Entity type (ORDER, FULFILMENT, etc.)",
+                },
+                id: {
+                    type: "string",
+                    description: "Entity ID (preferred)",
+                },
+                ref: {
+                    type: "string",
+                    description: "Entity ref (fallback)",
+                },
+                assertions: {
+                    type: "object",
+                    properties: {
+                        status: { type: "string", description: "Expected status" },
+                        type: { type: "string", description: "Expected type" },
+                        subtype: { type: "string", description: "Expected subtype" },
+                        attributes: {
+                            type: "object",
+                            additionalProperties: true,
+                            description: "Expected attribute key-value pairs",
+                        },
+                        edges: {
+                            type: "object",
+                            additionalProperties: {
+                                type: "object",
+                                properties: {
+                                    minCount: { type: "integer", minimum: 0 },
+                                    maxCount: { type: "integer", minimum: 0 },
+                                    status: { type: "string" },
+                                },
+                            },
+                            description: "Assertions on entity edges",
+                        },
+                    },
+                    description: "Assertion conditions",
+                },
+                poll: {
+                    type: "boolean",
+                    description: "Enable polling mode (retry until pass or timeout)",
+                },
+                timeoutMs: {
+                    type: "integer",
+                    minimum: 1000,
+                    maximum: 300000,
+                    description: "Polling timeout in ms (default: 60000)",
+                },
+                intervalMs: {
+                    type: "integer",
+                    minimum: 1000,
+                    maximum: 30000,
+                    description: "Polling interval in ms (default: 5000)",
+                },
+            },
+            required: ["entityType", "assertions"],
+            additionalProperties: false,
+        },
+    },
+];
+function buildEntityQuery(entityType, lookupById, edgeNames) {
+    const meta = getEntityMeta(entityType);
+    if (!meta) {
+        throw new ToolError("VALIDATION_ERROR", `Unsupported entity type: "${entityType}". Supported: ${SUPPORTED_ENTITY_TYPES.join(", ")}`);
+    }
+    const fields = [...meta.defaultFields];
+    // Add attributes edge for attribute assertions
+    if (!fields.includes("attributes")) {
+        fields.push("attributes { name type value }");
+    }
+    // Add requested edges
+    for (const edge of edgeNames) {
+        if (meta.edges.includes(edge)) {
+            fields.push(`${edge} { edges { node { id ref status type } } }`);
+        }
+    }
+    const fieldSelection = fields.join("\n    ");
+    if (lookupById) {
+        return `query GetEntity($id: ID!) {
+  ${meta.queryById}(id: $id) {
+    ${fieldSelection}
+  }
+}`;
+    }
+    return `query SearchEntity($ref: [String]) {
+  ${meta.queryRoot}(ref: $ref, first: 1) {
+    edges {
+      node {
+        ${fieldSelection}
+      }
+    }
+  }
+}`;
+}
+function evaluateAssertions(entity, assertions) {
+    const failures = [];
+    // Status assertion
+    if (assertions.status !== undefined) {
+        if (entity.status !== assertions.status) {
+            failures.push({
+                field: "status",
+                expected: assertions.status,
+                actual: entity.status,
+                message: `Expected status "${assertions.status}" but got "${entity.status}"`,
+            });
+        }
+    }
+    // Type assertion
+    if (assertions.type !== undefined) {
+        if (entity.type !== assertions.type) {
+            failures.push({
+                field: "type",
+                expected: assertions.type,
+                actual: entity.type,
+                message: `Expected type "${assertions.type}" but got "${entity.type}"`,
+            });
+        }
+    }
+    // Subtype assertion
+    if (assertions.subtype !== undefined) {
+        if (entity.subtype !== assertions.subtype) {
+            failures.push({
+                field: "subtype",
+                expected: assertions.subtype,
+                actual: entity.subtype,
+                message: `Expected subtype "${assertions.subtype}" but got "${entity.subtype}"`,
+            });
+        }
+    }
+    // Attribute assertions
+    if (assertions.attributes) {
+        const entityAttrs = entity.attributes;
+        const attrMap = new Map();
+        if (Array.isArray(entityAttrs)) {
+            for (const attr of entityAttrs) {
+                const rec = attr;
+                if (rec?.name)
+                    attrMap.set(rec.name, rec.value);
+            }
+        }
+        else if (entityAttrs && typeof entityAttrs === "object") {
+            for (const [key, val] of Object.entries(entityAttrs)) {
+                attrMap.set(key, val);
+            }
+        }
+        for (const [key, expectedValue] of Object.entries(assertions.attributes)) {
+            const actualValue = attrMap.get(key);
+            if (actualValue === undefined) {
+                failures.push({
+                    field: `attributes.${key}`,
+                    expected: expectedValue,
+                    actual: undefined,
+                    message: `Attribute "${key}" not found on entity`,
+                });
+            }
+            else if (JSON.stringify(actualValue) !== JSON.stringify(expectedValue)) {
+                failures.push({
+                    field: `attributes.${key}`,
+                    expected: expectedValue,
+                    actual: actualValue,
+                    message: `Attribute "${key}": expected ${JSON.stringify(expectedValue)} but got ${JSON.stringify(actualValue)}`,
+                });
+            }
+        }
+    }
+    // Edge assertions
+    if (assertions.edges) {
+        for (const [edgeName, edgeAssert] of Object.entries(assertions.edges)) {
+            const edgeData = entity[edgeName];
+            const edges = edgeData?.edges;
+            const nodes = (edges ?? [])
+                .map((e) => e?.node)
+                .filter(Boolean);
+            if (edgeAssert.minCount !== undefined && nodes.length < edgeAssert.minCount) {
+                failures.push({
+                    field: `edges.${edgeName}.count`,
+                    expected: `>= ${edgeAssert.minCount}`,
+                    actual: nodes.length,
+                    message: `Expected at least ${edgeAssert.minCount} ${edgeName} but found ${nodes.length}`,
+                });
+            }
+            if (edgeAssert.maxCount !== undefined && nodes.length > edgeAssert.maxCount) {
+                failures.push({
+                    field: `edges.${edgeName}.count`,
+                    expected: `<= ${edgeAssert.maxCount}`,
+                    actual: nodes.length,
+                    message: `Expected at most ${edgeAssert.maxCount} ${edgeName} but found ${nodes.length}`,
+                });
+            }
+            if (edgeAssert.status !== undefined) {
+                const nonMatching = nodes.filter((n) => n.status !== edgeAssert.status);
+                if (nonMatching.length > 0) {
+                    failures.push({
+                        field: `edges.${edgeName}.status`,
+                        expected: edgeAssert.status,
+                        actual: nonMatching.map((n) => n.status),
+                        message: `Expected all ${edgeName} to have status "${edgeAssert.status}" but ${nonMatching.length} do not`,
+                    });
+                }
+            }
+        }
+    }
+    return failures;
+}
+function requireTestClient(ctx) {
+    if (!ctx.client) {
+        throw new ToolError("CONFIG_ERROR", "SDK client is not available. Run config.validate and fix auth/base URL.");
+    }
+    return ctx.client;
+}
+async function fetchEntity(client, entityType, id, ref, edgeNames) {
+    const meta = getEntityMeta(entityType);
+    if (!meta)
+        return null;
+    const lookupById = !!id;
+    const query = buildEntityQuery(entityType, lookupById, edgeNames);
+    const variables = lookupById
+        ? { id }
+        : { ref: [ref] };
+    const response = await client.graphql({
+        query,
+        variables: variables,
+    });
+    const data = response?.data;
+    if (lookupById) {
+        return data?.[meta.queryById] ?? null;
+    }
+    const connection = data?.[meta.queryRoot];
+    const edges = connection?.edges;
+    return edges?.[0]?.node ?? null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Handle test.assert tool call.
+ */
+export async function handleTestAssert(args, ctx) {
+    const parsed = TestAssertInputSchema.parse(args);
+    if (!parsed.id && !parsed.ref) {
+        throw new ToolError("VALIDATION_ERROR", "Either id or ref must be provided for entity lookup.");
+    }
+    const client = requireTestClient(ctx);
+    const edgeNames = parsed.assertions.edges
+        ? Object.keys(parsed.assertions.edges)
+        : [];
+    const startTime = Date.now();
+    let attempts = 0;
+    let lastFailures = [];
+    let entity = null;
+    do {
+        attempts++;
+        entity = await fetchEntity(client, parsed.entityType, parsed.id, parsed.ref, edgeNames);
+        if (!entity) {
+            if (!parsed.poll || Date.now() - startTime >= parsed.timeoutMs) {
+                return {
+                    ok: true,
+                    passed: false,
+                    found: false,
+                    entityType: parsed.entityType,
+                    lookupBy: parsed.id ? "id" : "ref",
+                    lookupValue: parsed.id ?? parsed.ref,
+                    attempts,
+                    message: "Entity not found",
+                };
+            }
+            await sleep(parsed.intervalMs);
+            continue;
+        }
+        lastFailures = evaluateAssertions(entity, parsed.assertions);
+        if (lastFailures.length === 0) {
+            return {
+                ok: true,
+                passed: true,
+                entityType: parsed.entityType,
+                entity,
+                attempts,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        if (!parsed.poll || Date.now() - startTime >= parsed.timeoutMs) {
+            break;
+        }
+        await sleep(parsed.intervalMs);
+    } while (Date.now() - startTime < parsed.timeoutMs);
+    return {
+        ok: true,
+        passed: false,
+        entityType: parsed.entityType,
+        entity,
+        failures: lastFailures,
+        attempts,
+        durationMs: Date.now() - startTime,
+        message: `${lastFailures.length} assertion(s) failed after ${attempts} attempt(s)`,
+    };
+}