neuron-inspector 0.8.0 → 1.0.0

package/dist/automations/tools.js

@@ -0,0 +1,735 @@
+import { slugify } from "./store.js";
+// ── Tool Definitions ────────────────────────────────────────────────
+export function buildAutomationTools() {
+    return [
+        {
+            name: "neuron_auto_list",
+            description: "List all automation suites with their step counts, base URL, and setup/teardown status.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "neuron_auto_get",
+            description: "Get the full structure of an automation suite including all steps, setup, teardown, variables, and defaults.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: {
+                        type: "string",
+                        description: "Suite id (filename stem, e.g. 'onboarding-flow')",
+                    },
+                },
+                required: ["suite"],
+            },
+        },
+        {
+            name: "neuron_auto_create",
+            description: "Create a new automation suite with optional initial configuration. Returns error if a suite with the same slug already exists.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Human-readable suite name (e.g. 'User Onboarding Flow')",
+                    },
+                    description: {
+                        type: "string",
+                        description: "Optional description of what this suite automates",
+                    },
+                    base_url: {
+                        type: "string",
+                        description: "Optional base URL for all navigation steps",
+                    },
+                    variables: {
+                        type: "object",
+                        description: "Optional variables available to all steps (key-value pairs)",
+                    },
+                    defaults: {
+                        type: "object",
+                        description: "Optional default settings for all steps",
+                        properties: {
+                            timeout_ms: { type: "number" },
+                            on_error: { type: "string", enum: ["stop", "continue", "retry"] },
+                            wait_between_ms: { type: "number" },
+                            viewport: {
+                                type: "object",
+                                properties: {
+                                    width: { type: "number" },
+                                    height: { type: "number" },
+                                },
+                            },
+                        },
+                    },
+                    enabled: {
+                        type: "boolean",
+                        description: "Whether the suite is enabled (default: true). Disabled suites cannot be run.",
+                    },
+                    setup_recipe: {
+                        type: "object",
+                        description: "Recipe to run before setup steps (AI-driven goal-based automation)",
+                        properties: {
+                            slug: { type: "string", description: "Recipe slug (e.g. 'login-flow')" },
+                            variables: { type: "object", description: "Variable overrides for the recipe" },
+                        },
+                        required: ["slug"],
+                    },
+                    teardown_recipe: {
+                        type: "object",
+                        description: "Recipe to run after teardown steps (AI-driven cleanup)",
+                        properties: {
+                            slug: { type: "string", description: "Recipe slug (e.g. 'cleanup')" },
+                            variables: { type: "object", description: "Variable overrides for the recipe" },
+                        },
+                        required: ["slug"],
+                    },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "neuron_auto_update",
+            description: "Update a suite's configuration, steps, setup, or teardown. Pass null to clear a field. Omit fields to leave them unchanged.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id" },
+                    name: { type: "string", description: "New suite name" },
+                    enabled: { type: "boolean", description: "Enable or disable the suite" },
+                    description: { type: "string", description: "New description (empty string to clear)" },
+                    base_url: { type: "string", description: "New base URL (empty string to clear)" },
+                    variables: { type: "object", description: "New variables (replaces existing)" },
+                    defaults: {
+                        type: "object",
+                        description: "New defaults (merges with existing). Pass null to clear.",
+                        properties: {
+                            timeout_ms: { type: "number" },
+                            on_error: { type: "string", enum: ["stop", "continue", "retry"] },
+                            wait_between_ms: { type: "number" },
+                            viewport: {
+                                type: "object",
+                                properties: {
+                                    width: { type: "number" },
+                                    height: { type: "number" },
+                                },
+                            },
+                        },
+                    },
+                    steps: {
+                        type: "array",
+                        description: "New steps array (replaces existing). Pass empty array to clear.",
+                        items: { type: "object" },
+                    },
+                    setup: {
+                        type: "array",
+                        description: "New setup steps (replaces existing). Pass empty array to clear.",
+                        items: { type: "object" },
+                    },
+                    teardown: {
+                        type: "array",
+                        description: "New teardown steps (replaces existing). Pass empty array to clear.",
+                        items: { type: "object" },
+                    },
+                    setup_recipe: {
+                        type: ["object", "null"],
+                        description: "Recipe to run before setup steps. Pass null to clear.",
+                        properties: {
+                            slug: { type: "string", description: "Recipe slug" },
+                            variables: { type: "object", description: "Variable overrides" },
+                        },
+                        required: ["slug"],
+                    },
+                    teardown_recipe: {
+                        type: ["object", "null"],
+                        description: "Recipe to run after teardown steps. Pass null to clear.",
+                        properties: {
+                            slug: { type: "string", description: "Recipe slug" },
+                            variables: { type: "object", description: "Variable overrides" },
+                        },
+                        required: ["slug"],
+                    },
+                },
+                required: ["suite"],
+            },
+        },
+        {
+            name: "neuron_auto_delete",
+            description: "Delete an automation suite file.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id to delete" },
+                },
+                required: ["suite"],
+            },
+        },
+        {
+            name: "neuron_auto_run",
+            description: "Run a full automation suite including setup, all steps, and teardown. " +
+                "Requires active browser connection. Returns step-by-step results with assertions, extracted variables, timing, and screenshots.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id to run" },
+                    variables: {
+                        type: "object",
+                        description: "Optional runtime variable overrides (merged with suite variables)",
+                    },
+                },
+                required: ["suite"],
+            },
+        },
+        {
+            name: "neuron_auto_run_step",
+            description: "Run a single step from a suite for testing and debugging purposes. " +
+                "Requires active browser connection. Does not run setup/teardown. Returns step result with assertions and extracted data.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id" },
+                    step_id: { type: "string", description: "Step id to run" },
+                    variables: {
+                        type: "object",
+                        description: "Optional runtime variables available to this step",
+                    },
+                },
+                required: ["suite", "step_id"],
+            },
+        },
+        {
+            name: "neuron_auto_add_step",
+            description: "Add a new step to a suite. If index is provided, inserts at that position; otherwise appends to the end.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id" },
+                    step: {
+                        type: "object",
+                        description: "Step object with id, action, config, and optional assertions/extract/retry/timeout",
+                        properties: {
+                            id: { type: "string" },
+                            name: { type: "string" },
+                            action: { type: "string" },
+                            config: { type: "object" },
+                            assertions: { type: "array" },
+                            extract: { type: "object" },
+                            on_error: { type: "string", enum: ["stop", "continue", "retry"] },
+                            retry: {
+                                type: "object",
+                                properties: {
+                                    max: { type: "number" },
+                                    delay_ms: { type: "number" },
+                                },
+                            },
+                            wait_before_ms: { type: "number" },
+                            wait_after_ms: { type: "number" },
+                            timeout_ms: { type: "number" },
+                            disabled: { type: "boolean" },
+                        },
+                        required: ["id", "action", "config"],
+                    },
+                    index: {
+                        type: "number",
+                        description: "Optional index to insert at. Omit to append.",
+                    },
+                },
+                required: ["suite", "step"],
+            },
+        },
+        {
+            name: "neuron_auto_remove_step",
+            description: "Remove a step from a suite by its step_id.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id" },
+                    step_id: { type: "string", description: "Step id to remove" },
+                },
+                required: ["suite", "step_id"],
+            },
+        },
+        {
+            name: "neuron_auto_reorder",
+            description: "Reorder steps in a suite by providing a new ordered array of step IDs. " +
+                "All existing step IDs must be included.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id" },
+                    step_ids: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Ordered array of all step IDs in the new order",
+                    },
+                },
+                required: ["suite", "step_ids"],
+            },
+        },
+        {
+            name: "neuron_auto_import",
+            description: "Import an automation suite from a simple JSON format. " +
+                "Accepts { name, description?, base_url?, steps: [{ action, config, ... }] }. " +
+                "Converts to Neuron suite format and saves. Step IDs are auto-generated if missing.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    format: {
+                        type: "string",
+                        enum: ["simple"],
+                        description: "Import format. Currently only 'simple' is supported.",
+                    },
+                    data: {
+                        type: "object",
+                        description: "Suite data with name, optional description/base_url, and steps array",
+                        properties: {
+                            name: { type: "string" },
+                            description: { type: "string" },
+                            base_url: { type: "string" },
+                            steps: { type: "array", items: { type: "object" } },
+                        },
+                        required: ["name", "steps"],
+                    },
+                },
+                required: ["format", "data"],
+            },
+        },
+        {
+            name: "neuron_auto_export",
+            description: "Export a suite as a Playwright-style JavaScript test script. " +
+                "Returns executable code using @playwright/test conventions. " +
+                "Useful for migrating to Playwright or generating test templates.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    suite: { type: "string", description: "Suite id to export" },
+                },
+                required: ["suite"],
+            },
+        },
+    ];
+}
+// ── Handler ─────────────────────────────────────────────────────────
+export function buildAutomationHandler(store, executeSuite, executeStep) {
+    return async (name, args, ctx) => {
+        switch (name) {
+            case "neuron_auto_list": {
+                return store.list();
+            }
+            case "neuron_auto_get": {
+                const id = args.suite;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                return result.suite;
+            }
+            case "neuron_auto_create": {
+                const suiteName = args.name;
+                const id = slugify(suiteName);
+                if (!id)
+                    return { error: "Name produces an empty slug" };
+                // Check if suite already exists
+                const existing = await store.get(id);
+                if (existing) {
+                    return {
+                        error: `Suite '${id}' already exists at ${existing.location}`,
+                    };
+                }
+                // Build initial suite
+                const suite = {
+                    name: suiteName,
+                    steps: [],
+                };
+                if (args.enabled !== undefined)
+                    suite.enabled = args.enabled;
+                if (args.description)
+                    suite.description = args.description;
+                if (args.base_url)
+                    suite.base_url = args.base_url;
+                if (args.variables)
+                    suite.variables = args.variables;
+                if (args.defaults)
+                    suite.defaults = args.defaults;
+                if (args.setup_recipe)
+                    suite.setup_recipe = args.setup_recipe;
+                if (args.teardown_recipe)
+                    suite.teardown_recipe = args.teardown_recipe;
+                await store.save(id, suite);
+                return { id, name: suiteName, created: true };
+            }
+            case "neuron_auto_update": {
+                const id = args.suite;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                const suite = { ...result.suite };
+                const updates = [];
+                if (args.name !== undefined) {
+                    suite.name = args.name;
+                    updates.push("name");
+                }
+                if (args.enabled !== undefined) {
+                    suite.enabled = args.enabled;
+                    updates.push("enabled");
+                }
+                if (args.description !== undefined) {
+                    suite.description =
+                        args.description || undefined;
+                    updates.push("description");
+                }
+                if (args.base_url !== undefined) {
+                    suite.base_url = args.base_url || undefined;
+                    updates.push("base_url");
+                }
+                if (args.variables !== undefined) {
+                    suite.variables = args.variables;
+                    updates.push("variables");
+                }
+                if (args.defaults !== undefined) {
+                    suite.defaults =
+                        args.defaults === null
+                            ? undefined
+                            : args.defaults;
+                    updates.push("defaults");
+                }
+                if (args.steps !== undefined) {
+                    suite.steps = args.steps ?? [];
+                    updates.push("steps");
+                }
+                if (args.setup !== undefined) {
+                    suite.setup = args.setup ?? undefined;
+                    updates.push("setup");
+                }
+                if (args.teardown !== undefined) {
+                    suite.teardown = args.teardown ?? undefined;
+                    updates.push("teardown");
+                }
+                if (args.setup_recipe !== undefined) {
+                    suite.setup_recipe =
+                        args.setup_recipe === null
+                            ? undefined
+                            : args.setup_recipe;
+                    updates.push("setup_recipe");
+                }
+                if (args.teardown_recipe !== undefined) {
+                    suite.teardown_recipe =
+                        args.teardown_recipe === null
+                            ? undefined
+                            : args.teardown_recipe;
+                    updates.push("teardown_recipe");
+                }
+                if (updates.length === 0) {
+                    return { error: "No updates provided" };
+                }
+                await store.save(id, suite);
+                return { updated: true, suite: id, fields: updates };
+            }
+            case "neuron_auto_delete": {
+                const id = args.suite;
+                const deleted = await store.delete(id);
+                if (!deleted)
+                    return { error: `Suite '${id}' not found` };
+                return { deleted: true, id };
+            }
+            case "neuron_auto_run": {
+                if (!executeSuite) {
+                    return { error: "Suite execution not configured" };
+                }
+                if (!ctx) {
+                    return {
+                        error: "Browser connection required. Ensure an active browser session is connected.",
+                    };
+                }
+                const id = args.suite;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                if (result.suite.enabled === false) {
+                    return { error: "Suite is disabled" };
+                }
+                const variables = args.variables;
+                return executeSuite(result.suite, ctx, variables);
+            }
+            case "neuron_auto_run_step": {
+                if (!executeStep) {
+                    return { error: "Step execution not configured" };
+                }
+                if (!ctx) {
+                    return {
+                        error: "Browser connection required. Ensure an active browser session is connected.",
+                    };
+                }
+                const id = args.suite;
+                const stepId = args.step_id;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                // Find the step
+                const allSteps = [
+                    ...(result.suite.setup ?? []),
+                    ...result.suite.steps,
+                    ...(result.suite.teardown ?? []),
+                ];
+                const step = allSteps.find((s) => s.id === stepId);
+                if (!step) {
+                    return { error: `Step '${stepId}' not found in suite '${id}'` };
+                }
+                const variables = args.variables;
+                return executeStep(step, ctx, variables);
+            }
+            case "neuron_auto_add_step": {
+                const id = args.suite;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                const suite = { ...result.suite };
+                const newStep = args.step;
+                const index = args.index;
+                // Validate step has required fields
+                if (!newStep.id || !newStep.action || !newStep.config) {
+                    return {
+                        error: "Step must have id, action, and config fields",
+                    };
+                }
+                // Check for duplicate step ID
+                if (suite.steps.some((s) => s.id === newStep.id)) {
+                    return {
+                        error: `Step with id '${newStep.id}' already exists in suite`,
+                    };
+                }
+                // Insert or append
+                if (index !== undefined) {
+                    suite.steps.splice(index, 0, newStep);
+                }
+                else {
+                    suite.steps.push(newStep);
+                }
+                await store.save(id, suite);
+                return {
+                    added: true,
+                    suite: id,
+                    step_id: newStep.id,
+                    index: index ?? suite.steps.length - 1,
+                };
+            }
+            case "neuron_auto_remove_step": {
+                const id = args.suite;
+                const stepId = args.step_id;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                const suite = { ...result.suite };
+                const initialLength = suite.steps.length;
+                suite.steps = suite.steps.filter((s) => s.id !== stepId);
+                if (suite.steps.length === initialLength) {
+                    return { error: `Step '${stepId}' not found in suite '${id}'` };
+                }
+                await store.save(id, suite);
+                return { removed: true, suite: id, step_id: stepId };
+            }
+            case "neuron_auto_reorder": {
+                const id = args.suite;
+                const newOrder = args.step_ids;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                const suite = { ...result.suite };
+                const currentSteps = suite.steps;
+                // Validate that all step IDs are present
+                if (newOrder.length !== currentSteps.length) {
+                    return {
+                        error: `step_ids length (${newOrder.length}) does not match current steps count (${currentSteps.length})`,
+                    };
+                }
+                const currentIds = new Set(currentSteps.map((s) => s.id));
+                for (const id of newOrder) {
+                    if (!currentIds.has(id)) {
+                        return {
+                            error: `Step '${id}' not found in current steps`,
+                        };
+                    }
+                }
+                // Reorder steps
+                const stepMap = new Map(currentSteps.map((s) => [s.id, s]));
+                suite.steps = newOrder.map((id) => stepMap.get(id));
+                await store.save(id, suite);
+                return { reordered: true, suite: id, new_order: newOrder };
+            }
+            case "neuron_auto_import": {
+                const format = args.format;
+                if (format !== "simple") {
+                    return { error: `Unsupported import format: ${format}` };
+                }
+                const data = args.data;
+                // Validate input
+                if (!data.name || !Array.isArray(data.steps)) {
+                    return {
+                        error: "Import data must have 'name' string and 'steps' array",
+                    };
+                }
+                // Build suite from imported data
+                const suite = {
+                    name: data.name,
+                    steps: data.steps.map((s, i) => ({
+                        id: s.id ?? `step-${i + 1}`,
+                        name: s.name,
+                        action: s.action ?? "evaluate",
+                        config: s.config ?? {},
+                        assertions: s.assertions,
+                        extract: s.extract,
+                        on_error: s.on_error,
+                        retry: s.retry,
+                        wait_before_ms: s.wait_before_ms,
+                        wait_after_ms: s.wait_after_ms,
+                        timeout_ms: s.timeout_ms,
+                        disabled: s.disabled,
+                    })),
+                };
+                if (data.description)
+                    suite.description = data.description;
+                if (data.base_url)
+                    suite.base_url = data.base_url;
+                const id = slugify(data.name);
+                if (!id)
+                    return { error: "Name produces an empty slug" };
+                await store.save(id, suite);
+                return {
+                    imported: true,
+                    id,
+                    name: suite.name,
+                    step_count: suite.steps.length,
+                };
+            }
+            case "neuron_auto_export": {
+                const id = args.suite;
+                const result = await store.get(id);
+                if (!result)
+                    return { error: `Suite '${id}' not found` };
+                const suite = result.suite;
+                const lines = [];
+                // Header
+                lines.push("const { test, expect } = require('@playwright/test');");
+                lines.push("");
+                lines.push(`test('${suite.name}', async ({ page }) => {`);
+                // Helper to convert a step to Playwright code
+                const convertStep = (step, indent = "  ") => {
+                    const stepLines = [];
+                    // Add name comment if present
+                    if (step.name) {
+                        stepLines.push(`${indent}// ${step.name}`);
+                    }
+                    switch (step.action) {
+                        case "navigate":
+                            {
+                                const cfg = step.config;
+                                stepLines.push(`${indent}await page.goto('${cfg.url}');`);
+                            }
+                            break;
+                        case "click":
+                            {
+                                const cfg = step.config;
+                                if (cfg.text) {
+                                    stepLines.push(`${indent}await page.click('text=${cfg.text}');`);
+                                }
+                                else {
+                                    stepLines.push(`${indent}await page.click('${cfg.selector}');`);
+                                }
+                            }
+                            break;
+                        case "type":
+                            {
+                                const cfg = step.config;
+                                if (cfg.clear) {
+                                    stepLines.push(`${indent}await page.fill('${cfg.selector}', '${cfg.text}');`);
+                                }
+                                else {
+                                    stepLines.push(`${indent}await page.type('${cfg.selector}', '${cfg.text}');`);
+                                }
+                            }
+                            break;
+                        case "wait":
+                            {
+                                const cfg = step.config;
+                                if (cfg.type === "selector") {
+                                    stepLines.push(`${indent}await page.waitForSelector('${cfg.value}');`);
+                                }
+                                else if (cfg.type === "time") {
+                                    stepLines.push(`${indent}await page.waitForTimeout(${cfg.value});`);
+                                }
+                                else {
+                                    stepLines.push(`${indent}// wait (${cfg.type}): ${cfg.value}`);
+                                }
+                            }
+                            break;
+                        case "screenshot":
+                            {
+                                const cfg = step.config;
+                                const path = cfg.name ?? "screenshot.png";
+                                const options = cfg.full_page ? ", { fullPage: true }" : "";
+                                stepLines.push(`${indent}await page.screenshot({ path: '${path}'${options} });`);
+                            }
+                            break;
+                        case "evaluate":
+                            {
+                                const cfg = step.config;
+                                stepLines.push(`${indent}await page.evaluate(() => ${cfg.expression});`);
+                            }
+                            break;
+                        case "assert":
+                            {
+                                const cfg = step.config;
+                                if (cfg.check === "selector_exists") {
+                                    stepLines.push(`${indent}await expect(page.locator('${cfg.value}')).toBeVisible();`);
+                                }
+                                else if (cfg.check === "text_contains") {
+                                    stepLines.push(`${indent}await expect(page).toHaveText('${cfg.value}');`);
+                                }
+                                else {
+                                    stepLines.push(`${indent}// assert (${cfg.check}): ${cfg.value}`);
+                                }
+                            }
+                            break;
+                        default:
+                            stepLines.push(`${indent}// ${step.action}: ${JSON.stringify(step.config)}`);
+                    }
+                    return stepLines;
+                };
+                // Setup steps
+                if (suite.setup?.length) {
+                    lines.push("  // Setup");
+                    for (const step of suite.setup) {
+                        lines.push(...convertStep(step));
+                    }
+                    lines.push("");
+                }
+                // Main steps
+                for (const step of suite.steps) {
+                    if (step.disabled) {
+                        lines.push(`  // DISABLED: ${step.name ?? step.id}`);
+                        continue;
+                    }
+                    lines.push(...convertStep(step));
+                }
+                // Teardown steps
+                if (suite.teardown?.length) {
+                    lines.push("");
+                    lines.push("  // Teardown");
+                    for (const step of suite.teardown) {
+                        lines.push(...convertStep(step));
+                    }
+                }
+                lines.push("});");
+                const script = lines.join("\n");
+                return {
+                    suite: id,
+                    format: "playwright",
+                    script,
+                    filename: `${id}.spec.js`,
+                };
+            }
+            default:
+                return { error: `Unknown automation tool: ${name}` };
+        }
+    };
+}
+//# sourceMappingURL=tools.js.map