@fluentcommerce/fluent-mcp-extn 0.1.0

package/dist/environment-tools.js

@@ -0,0 +1,573 @@
+/**
+ * Environment tools: environment.discover, environment.validate
+ *
+ * Closes the setup loop — single-call environment snapshot and pre-flight checks
+ * for agentic workflows that need to understand what they're working with.
+ */
+import { z } from "zod";
+import { validateConfig } from "./config.js";
+import { ToolError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+export const EnvironmentDiscoverInputSchema = z.object({
+    include: z
+        .array(z.enum([
+        "retailer",
+        "locations",
+        "networks",
+        "catalogues",
+        "workflows",
+        "settings",
+        "modules",
+        "users",
+    ]))
+        .default(["retailer", "locations", "networks", "catalogues"])
+        .describe("Sections to include in the discovery snapshot."),
+});
+export const EnvironmentValidateInputSchema = z.object({
+    checks: z
+        .array(z.enum([
+        "auth",
+        "retailer",
+        "locations",
+        "inventory",
+        "workflows",
+        "settings",
+        "modules",
+    ]))
+        .default(["auth", "retailer", "locations"])
+        .describe("Pre-flight checks to run."),
+});
+// ---------------------------------------------------------------------------
+// Tool definitions (JSON Schema for MCP)
+// ---------------------------------------------------------------------------
+export const ENVIRONMENT_TOOL_DEFINITIONS = [
+    {
+        name: "environment.discover",
+        description: [
+            "Full environment snapshot in one call.",
+            "",
+            "Returns everything an agent needs to understand the Fluent environment:",
+            "- Retailer: id, ref, tradingName, status",
+            "- Locations: all locations with type, status, ref",
+            "- Networks: all networks with locations",
+            "- Catalogues: inventory + product + virtual catalogues",
+            "- Workflows: deployed workflow names and versions",
+            "- Settings: all retailer-scoped settings",
+            "- Modules: deployed modules",
+            "- Users: current authenticated user",
+            "",
+            "Each section is opt-in via 'include' array. Default: retailer, locations, networks, catalogues.",
+            "Returns refs, IDs, statuses, types — enough to construct valid mutations.",
+            "",
+            "LIMITATIONS:",
+            "- Locations and settings return first 100 items only (no auto-pagination).",
+            "- Workflows section uses transition API probe — may miss workflows with no user actions at initial state.",
+            "  Use 'fluent workflow list' via CLI for definitive workflow listing.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                include: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: [
+                            "retailer",
+                            "locations",
+                            "networks",
+                            "catalogues",
+                            "workflows",
+                            "settings",
+                            "modules",
+                            "users",
+                        ],
+                    },
+                    description: "Sections to include. Default: retailer, locations, networks, catalogues.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "environment.validate",
+        description: [
+            "Pre-flight environment validation.",
+            "",
+            "Runs configurable checks before E2E tests or deployments:",
+            "- auth: token valid, permissions sufficient",
+            "- retailer: exists, active",
+            "- locations: at least one warehouse exists",
+            "- inventory: at least one product with stock",
+            "- workflows: key workflows deployed (ORDER, FULFILMENT)",
+            "- settings: critical settings exist",
+            "- modules: expected modules deployed",
+            "",
+            "Returns pass/fail per check with severity and actionable messages.",
+        ].join("\n"),
+        inputSchema: {
+            type: "object",
+            properties: {
+                checks: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: [
+                            "auth",
+                            "retailer",
+                            "locations",
+                            "inventory",
+                            "workflows",
+                            "settings",
+                            "modules",
+                        ],
+                    },
+                    description: "Checks to run. Default: auth, retailer, locations.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Discovery queries
+// ---------------------------------------------------------------------------
+const QUERIES = {
+    retailer: `query {
+  me {
+    id username primaryEmail type status
+    primaryRetailer { id ref tradingName status primaryEmail }
+  }
+}`,
+    locations: `query($cursor: String) {
+  locations(first: 100, after: $cursor) {
+    edges { cursor node { id ref status type name supportPhoneNumber defaultCarrier createdOn } }
+    pageInfo { hasNextPage }
+  }
+}`,
+    networks: `query {
+  networks(first: 100) {
+    edges { node { id ref status type createdOn locations(first: 50) { edges { node { id ref } } } } }
+    pageInfo { hasNextPage }
+  }
+}`,
+    catalogues_inventory: `query {
+  inventoryCatalogues(first: 50) {
+    edges { node { id ref status type name createdOn } }
+  }
+}`,
+    catalogues_product: `query {
+  productCatalogues(first: 50) {
+    edges { node { id ref status type name createdOn } }
+  }
+}`,
+    catalogues_virtual: `query {
+  virtualCatalogues(first: 50) {
+    edges { node { id ref status type inventoryCatalogueRef productCatalogueRef createdOn } }
+  }
+}`,
+    settings: `query($cursor: String) {
+  settings(first: 100, after: $cursor) {
+    edges { cursor node { id name value context contextId createdOn updatedOn } }
+    pageInfo { hasNextPage }
+  }
+}`,
+    users: `query {
+  me {
+    id username primaryEmail type status
+    roles { role { name permissions { name } } }
+    primaryRetailer { id ref tradingName }
+    primaryLocation { id ref name type }
+  }
+}`,
+};
+function requireEnvClient(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 queryGraphQL(client, query, variables) {
+    const payload = {
+        query,
+        ...(variables
+            ? { variables: variables }
+            : {}),
+    };
+    const response = await client.graphql(payload);
+    return response?.data ?? {};
+}
+function extractNodes(connection) {
+    if (!connection || typeof connection !== "object")
+        return [];
+    const edges = connection.edges;
+    if (!Array.isArray(edges))
+        return [];
+    return edges
+        .map((edge) => {
+        if (!edge || typeof edge !== "object")
+            return null;
+        return edge.node;
+    })
+        .filter((n) => n !== null);
+}
+/**
+ * Handle environment.discover tool call.
+ */
+export async function handleEnvironmentDiscover(args, ctx) {
+    const parsed = EnvironmentDiscoverInputSchema.parse(args);
+    const client = requireEnvClient(ctx);
+    const result = {};
+    for (const section of parsed.include) {
+        try {
+            switch (section) {
+                case "retailer":
+                case "users": {
+                    const data = await queryGraphQL(client, QUERIES[section]);
+                    const me = data.me;
+                    if (section === "retailer") {
+                        result.retailer = me?.primaryRetailer ?? null;
+                        result.user = {
+                            id: me?.id,
+                            username: me?.username,
+                            type: me?.type,
+                            status: me?.status,
+                        };
+                    }
+                    else {
+                        result.users = me;
+                    }
+                    break;
+                }
+                case "locations": {
+                    const data = await queryGraphQL(client, QUERIES.locations, {
+                        cursor: null,
+                    });
+                    const locationNodes = extractNodes(data.locations);
+                    const locPageInfo = data.locations?.pageInfo;
+                    result.locations = locationNodes;
+                    if (locPageInfo?.hasNextPage) {
+                        result.locationsNote = `Showing first ${locationNodes.length} locations. Use graphql.queryAll for complete list.`;
+                    }
+                    break;
+                }
+                case "networks": {
+                    const data = await queryGraphQL(client, QUERIES.networks);
+                    result.networks = extractNodes(data.networks);
+                    break;
+                }
+                case "catalogues": {
+                    const [invData, prodData, virtData] = await Promise.all([
+                        queryGraphQL(client, QUERIES.catalogues_inventory),
+                        queryGraphQL(client, QUERIES.catalogues_product),
+                        queryGraphQL(client, QUERIES.catalogues_virtual),
+                    ]);
+                    result.catalogues = {
+                        inventory: extractNodes(invData.inventoryCatalogues),
+                        product: extractNodes(prodData.productCatalogues),
+                        virtual: extractNodes(virtData.virtualCatalogues),
+                    };
+                    break;
+                }
+                case "workflows": {
+                    // Workflows are not directly queryable via standard GraphQL.
+                    // We use the workflow.transitions API to discover deployed workflow types.
+                    const retailerId = ctx.config.retailerId;
+                    if (retailerId) {
+                        try {
+                            // Query transitions for common entity types to discover workflows
+                            const entityTypes = ["ORDER", "FULFILMENT", "ARTICLE"];
+                            const workflowInfo = [];
+                            for (const entityType of entityTypes) {
+                                try {
+                                    const transitions = await client.getTransitions({
+                                        triggers: [{ type: entityType, retailerId }],
+                                    });
+                                    if (transitions) {
+                                        workflowInfo.push({
+                                            entityType,
+                                            hasWorkflow: true,
+                                            transitions: transitions,
+                                        });
+                                    }
+                                }
+                                catch {
+                                    workflowInfo.push({
+                                        entityType,
+                                        hasWorkflow: false,
+                                    });
+                                }
+                            }
+                            result.workflows = workflowInfo;
+                        }
+                        catch {
+                            result.workflows = { error: "Unable to discover workflows" };
+                        }
+                    }
+                    else {
+                        result.workflows = {
+                            note: "retailerId required for workflow discovery",
+                        };
+                    }
+                    break;
+                }
+                case "settings": {
+                    const data = await queryGraphQL(client, QUERIES.settings, {
+                        cursor: null,
+                    });
+                    const settingNodes = extractNodes(data.settings);
+                    const settPageInfo = data.settings?.pageInfo;
+                    result.settings = settingNodes;
+                    if (settPageInfo?.hasNextPage) {
+                        result.settingsNote = `Showing first ${settingNodes.length} settings. Use graphql.queryAll for complete list.`;
+                    }
+                    break;
+                }
+                case "modules": {
+                    // Modules discoverable via plugin.list
+                    try {
+                        const plugins = await client.getPlugins();
+                        if (plugins && typeof plugins === "object") {
+                            const pluginMap = plugins;
+                            const moduleNames = new Set();
+                            for (const key of Object.keys(pluginMap)) {
+                                // Keys are like ACCOUNT.context.RuleName — extract module context
+                                const parts = key.split(".");
+                                if (parts.length >= 2)
+                                    moduleNames.add(parts[1]);
+                            }
+                            result.modules = {
+                                pluginCount: Object.keys(pluginMap).length,
+                                contexts: [...moduleNames],
+                            };
+                        }
+                    }
+                    catch {
+                        result.modules = { error: "Unable to fetch module list" };
+                    }
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            result[section] = {
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    return { ok: true, ...result };
+}
+/**
+ * Handle environment.validate tool call.
+ */
+export async function handleEnvironmentValidate(args, ctx) {
+    const parsed = EnvironmentValidateInputSchema.parse(args);
+    const checks = [];
+    for (const check of parsed.checks) {
+        try {
+            switch (check) {
+                case "auth": {
+                    const validation = validateConfig(ctx.config);
+                    checks.push({
+                        name: "auth",
+                        passed: validation.isReadyForApiCalls,
+                        message: validation.isReadyForApiCalls
+                            ? `Authenticated via ${validation.authStrategy}`
+                            : `Auth not ready: ${validation.errors.join(", ")}`,
+                        severity: validation.isReadyForApiCalls ? "info" : "error",
+                    });
+                    break;
+                }
+                case "retailer": {
+                    if (!ctx.client) {
+                        checks.push({
+                            name: "retailer",
+                            passed: false,
+                            message: "Cannot verify retailer — SDK client not available",
+                            severity: "error",
+                        });
+                        break;
+                    }
+                    const data = await queryGraphQL(ctx.client, QUERIES.retailer);
+                    const me = data.me;
+                    const retailer = me?.primaryRetailer;
+                    if (retailer) {
+                        checks.push({
+                            name: "retailer",
+                            passed: retailer.status === "ACTIVE",
+                            message: `Retailer ${retailer.ref} (${retailer.tradingName}): ${retailer.status}`,
+                            severity: retailer.status === "ACTIVE" ? "info" : "warning",
+                        });
+                    }
+                    else {
+                        checks.push({
+                            name: "retailer",
+                            passed: false,
+                            message: "No primary retailer found for authenticated user",
+                            severity: "error",
+                        });
+                    }
+                    break;
+                }
+                case "locations": {
+                    if (!ctx.client) {
+                        checks.push({
+                            name: "locations",
+                            passed: false,
+                            message: "Cannot verify locations — SDK client not available",
+                            severity: "error",
+                        });
+                        break;
+                    }
+                    const data = await queryGraphQL(ctx.client, QUERIES.locations, {
+                        cursor: null,
+                    });
+                    const locations = extractNodes(data.locations);
+                    const warehouses = locations.filter((l) => l.type === "WAREHOUSE" || l.type === "STORE");
+                    checks.push({
+                        name: "locations",
+                        passed: warehouses.length > 0,
+                        message: `${locations.length} location(s) found, ${warehouses.length} warehouse/store`,
+                        severity: warehouses.length > 0 ? "info" : "warning",
+                    });
+                    break;
+                }
+                case "inventory": {
+                    if (!ctx.client) {
+                        checks.push({
+                            name: "inventory",
+                            passed: false,
+                            message: "Cannot verify inventory — SDK client not available",
+                            severity: "error",
+                        });
+                        break;
+                    }
+                    const invQuery = `query {
+  inventoryPositions(first: 5) {
+    edges { node { id ref onHand type status } }
+  }
+}`;
+                    const data = await queryGraphQL(ctx.client, invQuery);
+                    const positions = extractNodes(data.inventoryPositions);
+                    const withStock = positions.filter((p) => typeof p.onHand === "number" && p.onHand > 0);
+                    checks.push({
+                        name: "inventory",
+                        passed: withStock.length > 0,
+                        message: `${positions.length} inventory position(s) sampled, ${withStock.length} with stock > 0`,
+                        severity: withStock.length > 0 ? "info" : "warning",
+                    });
+                    break;
+                }
+                case "workflows": {
+                    if (!ctx.client || !ctx.config.retailerId) {
+                        checks.push({
+                            name: "workflows",
+                            passed: false,
+                            message: "Cannot verify workflows — client or retailerId missing",
+                            severity: "warning",
+                        });
+                        break;
+                    }
+                    const entityTypes = ["ORDER", "FULFILMENT"];
+                    let deployedCount = 0;
+                    const missing = [];
+                    for (const entityType of entityTypes) {
+                        try {
+                            const transitions = await ctx.client.getTransitions({
+                                triggers: [
+                                    { type: entityType, retailerId: ctx.config.retailerId },
+                                ],
+                            });
+                            if (transitions)
+                                deployedCount++;
+                        }
+                        catch {
+                            missing.push(entityType);
+                        }
+                    }
+                    checks.push({
+                        name: "workflows",
+                        passed: missing.length === 0,
+                        message: missing.length === 0
+                            ? `${deployedCount} workflow type(s) verified (${entityTypes.join(", ")})`
+                            : `Missing workflows for: ${missing.join(", ")}`,
+                        severity: missing.length === 0 ? "info" : "warning",
+                    });
+                    break;
+                }
+                case "settings": {
+                    if (!ctx.client) {
+                        checks.push({
+                            name: "settings",
+                            passed: false,
+                            message: "Cannot verify settings — SDK client not available",
+                            severity: "warning",
+                        });
+                        break;
+                    }
+                    const data = await queryGraphQL(ctx.client, QUERIES.settings, {
+                        cursor: null,
+                    });
+                    const settings = extractNodes(data.settings);
+                    checks.push({
+                        name: "settings",
+                        passed: settings.length > 0,
+                        message: `${settings.length} setting(s) found in environment`,
+                        severity: settings.length > 0 ? "info" : "warning",
+                    });
+                    break;
+                }
+                case "modules": {
+                    if (!ctx.client) {
+                        checks.push({
+                            name: "modules",
+                            passed: false,
+                            message: "Cannot verify modules — SDK client not available",
+                            severity: "warning",
+                        });
+                        break;
+                    }
+                    try {
+                        const plugins = await ctx.client.getPlugins();
+                        const count = plugins
+                            ? Object.keys(plugins).length
+                            : 0;
+                        checks.push({
+                            name: "modules",
+                            passed: count > 0,
+                            message: `${count} registered rule(s) found`,
+                            severity: count > 0 ? "info" : "warning",
+                        });
+                    }
+                    catch {
+                        checks.push({
+                            name: "modules",
+                            passed: false,
+                            message: "Unable to fetch plugin registry",
+                            severity: "warning",
+                        });
+                    }
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            checks.push({
+                name: check,
+                passed: false,
+                message: error instanceof Error ? error.message : String(error),
+                severity: "error",
+            });
+        }
+    }
+    const allPassed = checks.every((c) => c.passed);
+    return {
+        ok: true,
+        ready: allPassed,
+        checks,
+        summary: allPassed
+            ? `All ${checks.length} check(s) passed.`
+            : `${checks.filter((c) => !c.passed).length} of ${checks.length} check(s) failed.`,
+    };
+}