neuron-inspector 1.2.0 → 1.3.0

package/dist/collections/tools.js

@@ -1,9 +1,103 @@
 import { readFile } from "node:fs/promises";
 import * as YAML from "yaml";
 import { slugify } from "./store.js";
-import { executeEndpoint, executeFolder, executeCollection, executeScenario } from "./executor.js";
+import { executeEndpoint, executeFolder, executeCollection, resolveStepRef, normalizePoll } from "./executor.js";
+import { assertTimeZone } from "./dynamic-vars.js";
+import { pickEnvironment, runInputsFor, runScenario } from "./scenario-run.js";
+import { sanitizeInputDeclarations, mergeInputDeclarations, prepareInputs, describeInputs, SecretMasker } from "./masking.js";
 import { fromPostmanV21, toPostmanV21 } from "./postman.js";
 import { mergeCollections } from "./merge.js";
+const INPUTS_SCHEMA = {
+    type: "array",
+    description: "Values supplied at run time, used as {{name}}. Declarations only: never put a value here. " +
+        "Secret inputs are kept in memory for one run and shown as ••• in every result.",
+    items: {
+        type: "object",
+        properties: {
+            name: { type: "string" },
+            label: { type: "string" },
+            description: { type: "string" },
+            secret: { type: "boolean", description: "Mask the value everywhere and never store it" },
+            required: { type: "boolean", description: "Default true" },
+            default: { type: "string", description: "Fallback for non-secret inputs only" },
+        },
+        required: ["name"],
+    },
+};
+const RUN_INPUT_VALUES_SCHEMA = {
+    type: "object",
+    description: "Values for the declared inputs, e.g. { client_id: '…', client_secret: '…' }. " +
+        "Held in memory for this run only; values of secret inputs are masked as ••• in the result.",
+};
+const STEP_SCHEMA = {
+    type: "object",
+    properties: {
+        ref: {
+            type: "string",
+            description: "Endpoint reference: 'folder/<endpoint name>' or 'folder/METHOD /path' (method case-insensitive)",
+        },
+        overrides: {
+            type: "object",
+            description: "Per-step overrides for headers, body, tests, path, variables",
+            properties: {
+                headers: { type: "object" },
+                body: {},
+                tests: { type: "array" },
+                path: { type: "string" },
+                variables: { type: "object" },
+            },
+        },
+        poll: {
+            type: "object",
+            description: "Repeat this request until every 'until' assertion passes. Each attempt is recorded. " +
+                "Fails the step (and halts the scenario) if max_attempts runs out.",
+            properties: {
+                until: { type: "array", description: "Assertions: [{ check, op, expect }]. op 'in' takes an array expect." },
+                interval_ms: { type: "number", description: "Wait between attempts (default 2000, 100–60000)" },
+                max_attempts: { type: "number", description: "Default 10, max 120" },
+            },
+            required: ["until"],
+        },
+    },
+    required: ["ref"],
+};
+const COLLECTION_DATA_SCHEMA = {
+    type: "object",
+    description: "Run this collection object instead of loading one from disk (used by the extension for its local collections)",
+};
+/** Step refs that won't resolve, so a scenario can be fixed before it runs. */
+function checkStepRefs(collection, steps) {
+    const problems = [];
+    steps.forEach((step, i) => {
+        const r = resolveStepRef(collection, step.ref);
+        if ("error" in r)
+            problems.push(`step ${i + 1}: ${r.error}`);
+        if (step.poll) {
+            try {
+                normalizePoll(step.poll);
+            }
+            catch (err) {
+                problems.push(`step ${i + 1}: ${err.message}`);
+            }
+        }
+    });
+    return problems;
+}
+function validateSteps(raw) {
+    if (!Array.isArray(raw))
+        throw new Error("steps must be an array");
+    return raw.map((step, i) => {
+        if (!step || typeof step !== "object" || typeof step.ref !== "string") {
+            throw new Error(`step ${i + 1} needs a 'ref'`);
+        }
+        const s = step;
+        if (s.poll !== undefined)
+            normalizePoll(s.poll);
+        return s;
+    });
+}
+/** Cancellation flags for runs started with a run_id. */
+const activeRuns = new Map();
 export function buildCollectionTools() {
     return [
         {
@@ -123,7 +217,8 @@ export function buildCollectionTools() {
                     },
                     extract: {
                         type: "object",
-                        description: "Variables to extract from the response, e.g. { bot_id: 'body.id' }",
+                        description: "Variables to extract from the response, e.g. { bot_id: 'body.id' }. " +
+                            "Use { access_token: { path: 'body.access_token', mask: true } } to show the value as ••• in every result for the rest of the run.",
                     },
                     body_mode: {
                         type: "string",
@@ -263,6 +358,8 @@ export function buildCollectionTools() {
                     variables: { type: "object", description: "Environment variables (key-value pairs)" },
                     headers: { type: "object", description: "Environment-specific header overrides" },
                     timeout_ms: { type: "number", description: "Environment-specific timeout" },
+                    inputs: INPUTS_SCHEMA,
+                    timezone: { type: "string", description: "IANA zone for {{$today}} and formatted {{$now}}, e.g. 'Africa/Lagos' (default: defaults.timezone, else UTC)" },
                 },
                 required: ["collection", "name", "base_url"],
             },
@@ -321,6 +418,7 @@ export function buildCollectionTools() {
         {
             name: "neuron_api_set_defaults",
             description: "Set or update collection-level defaults. Merges with existing defaults. " +
+                "pre_request / post_response scripts here run before each endpoint's own script (same sandbox and nr API), so endpoints can override what they set. " +
                 "Pass null for auth to clear it. Omit fields to leave them unchanged.",
             inputSchema: {
                 type: "object",
@@ -328,6 +426,7 @@ export function buildCollectionTools() {
                     collection: { type: "string", description: "Collection id" },
                     headers: { type: "object", description: "Default headers (key-value pairs)" },
                     variables: { type: "object", description: "Default variables (key-value pairs)" },
+                    timezone: { type: "string", description: "IANA zone for {{$today}} and formatted {{$now}}, e.g. 'Africa/Lagos' (default UTC). An environment's timezone wins." },
                     timeout_ms: { type: "number", description: "Default timeout (ms)" },
                     auth: {
                         type: "object",
@@ -444,34 +543,20 @@ export function buildCollectionTools() {
         // ── Scenario management ───────────────────────────────────
         {
             name: "neuron_api_create_scenario",
-            description: "Create a new scenario in a collection. Steps reference endpoints as 'folder/method path' (e.g. 'auth/POST /login').",
+            description: "Create a new scenario in a collection. Steps reference endpoints as 'folder/<endpoint name>' or " +
+                "'folder/METHOD /path' (e.g. 'auth/POST /login'). A step can poll until assertions pass. " +
+                "Declare run-time values (client ids, secrets) in 'inputs' and pass them when you run.",
             inputSchema: {
                 type: "object",
                 properties: {
                     collection: { type: "string", description: "Collection id" },
                     name: { type: "string", description: "Scenario name" },
                     description: { type: "string", description: "Scenario description" },
+                    inputs: INPUTS_SCHEMA,
                     steps: {
                         type: "array",
-                        description: "Ordered steps. Each step has a 'ref' (folder/METHOD path) and optional overrides.",
-                        items: {
-                            type: "object",
-                            properties: {
-                                ref: { type: "string", description: "Endpoint reference: 'folder/METHOD path'" },
-                                overrides: {
-                                    type: "object",
-                                    description: "Per-step overrides for headers, body, tests, path, variables",
-                                    properties: {
-                                        headers: { type: "object" },
-                                        body: {},
-                                        tests: { type: "array" },
-                                        path: { type: "string" },
-                                        variables: { type: "object" },
-                                    },
-                                },
-                            },
-                            required: ["ref"],
-                        },
+                        description: "Ordered steps. Each step has a 'ref', optional overrides and an optional poll.",
+                        items: STEP_SCHEMA,
                     },
                 },
                 required: ["collection", "name", "steps"],
@@ -479,24 +564,18 @@ export function buildCollectionTools() {
         },
         {
             name: "neuron_api_update_scenario",
-            description: "Update a scenario's description or steps.",
+            description: "Update a scenario's description, inputs or steps.",
             inputSchema: {
                 type: "object",
                 properties: {
                     collection: { type: "string", description: "Collection id" },
                     scenario: { type: "string", description: "Scenario name" },
                     description: { type: "string", description: "New description" },
+                    inputs: INPUTS_SCHEMA,
                     steps: {
                         type: "array",
                         description: "New ordered steps (replaces existing)",
-                        items: {
-                            type: "object",
-                            properties: {
-                                ref: { type: "string" },
-                                overrides: { type: "object" },
-                            },
-                            required: ["ref"],
-                        },
+                        items: STEP_SCHEMA,
                     },
                 },
                 required: ["collection", "scenario"],
@@ -551,6 +630,7 @@ export function buildCollectionTools() {
                     follow_authorization: { type: "boolean", description: "Override: retain Authorization on cross-host redirects" },
                     remove_referer: { type: "boolean", description: "Override: remove Referer header on redirect" },
                     encode_url: { type: "boolean", description: "Override: encode URL automatically" },
+                    inputs: RUN_INPUT_VALUES_SCHEMA,
                 },
                 required: ["collection"],
             },
@@ -559,16 +639,44 @@ export function buildCollectionTools() {
             name: "neuron_api_run_scenario",
             description: "Run a named scenario: an ordered sequence of endpoint calls with variable chaining. " +
                 "Extracted variables from each step are available to subsequent steps via {{variable}} references. " +
-                "Execution halts on the first step that fails (HTTP error or assertion failure). " +
-                "Steps can include overrides for headers, body, tests, path, and variables.",
+                "Execution halts on the first step that fails (HTTP error, assertion failure, or a poll that never succeeds). " +
+                "Steps can include overrides for headers, body, tests, path, and variables, and a poll. " +
+                "Pass values for the scenario's/environment's declared inputs in 'inputs'; secret ones are masked as ••• in the result. " +
+                "The environment you pass is the one used, whatever the collection's active environment is.",
             inputSchema: {
                 type: "object",
                 properties: {
                     collection: { type: "string", description: "Collection id" },
                     scenario: { type: "string", description: "Scenario name (key under 'scenarios' in the collection)" },
                     environment: { type: "string", description: "Environment name (defaults to active_environment)" },
+                    inputs: RUN_INPUT_VALUES_SCHEMA,
+                    run_id: { type: "string", description: "Optional id so the run can be cancelled with neuron_api_cancel_run" },
+                    collection_data: COLLECTION_DATA_SCHEMA,
                 },
-                required: ["collection", "scenario"],
+                required: ["scenario"],
+            },
+        },
+        {
+            name: "neuron_api_get_run_inputs",
+            description: "List the inputs a scenario run will ask for (environment inputs merged with the scenario's). " +
+                "Returns declarations only (name, label, secret, required), never values.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    collection: { type: "string", description: "Collection id" },
+                    scenario: { type: "string", description: "Scenario name (omit for environment inputs only)" },
+                    environment: { type: "string", description: "Environment name (defaults to active_environment)" },
+                    collection_data: COLLECTION_DATA_SCHEMA,
+                },
+            },
+        },
+        {
+            name: "neuron_api_cancel_run",
+            description: "Stop a scenario run started with a run_id. It halts before its next request or poll attempt.",
+            inputSchema: {
+                type: "object",
+                properties: { run_id: { type: "string" } },
+                required: ["run_id"],
             },
         },
         // ── Query and generation ─────────────────────────────────
@@ -693,7 +801,24 @@ export function buildCollectionTools() {
 }
 // ── Handler ─────────────────────────────────────────────────────
 export function buildCollectionHandler(store, httpExecutor, pipeline, assertionEvaluator, scriptRunner) {
-    return async function handleCollectionTool(name, args) {
+    /** Load the collection a run targets: inline data from the caller, else the store. */
+    async function loadForRun(args) {
+        if (args.collection_data !== undefined) {
+            const data = args.collection_data;
+            if (!data || typeof data !== "object" || Array.isArray(data))
+                return { error: "collection_data must be a collection object" };
+            const c = data;
+            return { id: args.collection || slugify(c.name || "inline"), collection: c };
+        }
+        const id = args.collection;
+        if (!id)
+            return { error: "Provide 'collection' (id) or 'collection_data'" };
+        const result = await store.get(id);
+        if (!result)
+            return { error: `Collection '${id}' not found` };
+        return { id, collection: result.collection };
+    }
+    return async function handleCollectionTool(name, args, hooks) {
         switch (name) {
             case "neuron_api_list_collections": {
                 return store.list();
@@ -785,6 +910,13 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                     env.headers = args.headers;
                 if (args.timeout_ms)
                     env.timeout_ms = args.timeout_ms;
+                if (typeof args.timezone === "string" && args.timezone) {
+                    assertTimeZone(args.timezone);
+                    env.timezone = args.timezone;
+                }
+                const envInputs = sanitizeInputDeclarations(args.inputs);
+                if (envInputs)
+                    env.inputs = envInputs;
                 await store.setEnvironment(id, envName, env);
                 return { set: true, collection: id, environment: slugify(envName) };
             }
@@ -837,6 +969,8 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                 const { collection: _c, ...defaults } = args;
                 if (Object.keys(defaults).length === 0)
                     return { error: "No defaults provided" };
+                if (typeof defaults.timezone === "string" && defaults.timezone)
+                    assertTimeZone(defaults.timezone);
                 await store.setDefaults(id, defaults);
                 return { set: true, collection: id, fields: Object.keys(defaults) };
             }
@@ -901,12 +1035,22 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                 const id = args.collection;
                 const scenarioName = args.name;
                 const scenario = {
-                    steps: args.steps,
+                    steps: validateSteps(args.steps),
                 };
                 if (args.description)
                     scenario.description = args.description;
-                await store.createScenario(id, scenarioName, scenario);
-                return { created: true, collection: id, scenario: scenarioName, step_count: scenario.steps.length };
+                const scenarioInputs = sanitizeInputDeclarations(args.inputs);
+                if (scenarioInputs)
+                    scenario.inputs = scenarioInputs;
+                const updated = await store.createScenario(id, scenarioName, scenario);
+                const warnings = checkStepRefs(updated, scenario.steps);
+                return {
+                    created: true,
+                    collection: id,
+                    scenario: scenarioName,
+                    step_count: scenario.steps.length,
+                    ...(warnings.length ? { warnings } : {}),
+                };
             }
             case "neuron_api_update_scenario": {
                 const id = args.collection;
@@ -915,11 +1059,14 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                 if (args.description !== undefined)
                     updates.description = args.description;
                 if (args.steps !== undefined)
-                    updates.steps = args.steps;
+                    updates.steps = validateSteps(args.steps);
+                if (args.inputs !== undefined)
+                    updates.inputs = sanitizeInputDeclarations(args.inputs) ?? [];
                 if (Object.keys(updates).length === 0)
                     return { error: "No updates provided" };
-                await store.updateScenario(id, scenarioName, updates);
-                return { updated: true, collection: id, scenario: scenarioName };
+                const updated = await store.updateScenario(id, scenarioName, updates);
+                const warnings = checkStepRefs(updated, updated.scenarios?.[scenarioName]?.steps ?? []);
+                return { updated: true, collection: id, scenario: scenarioName, ...(warnings.length ? { warnings } : {}) };
             }
             case "neuron_api_delete_scenario": {
                 const id = args.collection;
@@ -938,6 +1085,7 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                         name: key,
                         description: s.description ?? null,
                         step_count: s.steps?.length ?? 0,
+                        inputs: describeInputs(s.inputs ?? []),
                     })),
                 };
             }
@@ -946,25 +1094,26 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                 if (!httpExecutor || !pipeline || !assertionEvaluator) {
                     return { error: "HTTP executor not configured" };
                 }
-                const id = args.collection;
-                const result = await store.get(id);
-                if (!result)
-                    return { error: `Collection '${id}' not found` };
-                const { collection } = result;
-                // Resolve environment
-                const envName = args.environment ?? collection.active_environment;
-                if (!envName) {
-                    return { error: "No environment specified and no active_environment set on the collection" };
-                }
-                const environment = collection.environments?.[slugify(envName)];
-                if (!environment) {
-                    return { error: `Environment '${envName}' not found in collection '${id}'` };
+                const loaded = await loadForRun(args);
+                if ("error" in loaded)
+                    return loaded;
+                const { id, collection } = loaded;
+                const picked = pickEnvironment(collection, id, args.environment);
+                if ("error" in picked)
+                    return picked;
+                const { key: envKey, environment } = picked;
+                const declared = mergeInputDeclarations(environment.inputs);
+                const prepared = prepareInputs(declared, args.inputs);
+                if (prepared.missing.length) {
+                    return { error: `Missing required input(s): ${prepared.missing.join(", ")}`, inputs: describeInputs(declared) };
                 }
+                const masker = new SecretMasker(prepared.secrets);
+                const runCtx = { environmentName: envKey, inputs: prepared.values, onSecret: (v) => masker.add(v) };
                 const hasFolder = typeof args.folder === "string";
                 const hasEndpoint = typeof args.method === "string" && typeof args.path === "string";
                 // Mode 3: Collection-wide run (no folder specified)
                 if (!hasFolder) {
-                    return executeCollection({
+                    return masker.mask(await executeCollection({
                         collectionId: id,
                         collection,
                         environment,
@@ -972,16 +1121,17 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                         pipeline,
                         assertionEvaluator,
                         scriptRunner,
-                    });
+                        ...runCtx,
+                    }));
                 }
                 const folderKey = slugify(args.folder);
-                const folder = collection.folders?.[folderKey];
+                const folder = collection.folders?.[folderKey] ?? collection.folders?.[args.folder];
                 if (!folder) {
                     return { error: `Folder '${args.folder}' not found in collection '${id}'` };
                 }
                 // Mode 2: Folder run (folder but no method/path)
                 if (!hasEndpoint) {
-                    return executeFolder({
+                    return masker.mask(await executeFolder({
                         folderKey,
                         collection,
                         environment,
@@ -990,7 +1140,8 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                         pipeline,
                         assertionEvaluator,
                         scriptRunner,
-                    });
+                        ...runCtx,
+                    }));
                 }
                 // Mode 1: Single endpoint
                 const method = args.method.toUpperCase();
@@ -1023,7 +1174,7 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                         runSettings.encode_url = args.encode_url;
                     endpoint.settings = runSettings;
                 }
-                return executeEndpoint({
+                return masker.mask(await executeEndpoint({
                     collection,
                     environment,
                     folder,
@@ -1032,43 +1183,55 @@ export function buildCollectionHandler(store, httpExecutor, pipeline, assertionE
                     pipeline,
                     assertionEvaluator,
                     scriptRunner,
-                });
+                    ...runCtx,
+                }));
             }
             case "neuron_api_run_scenario": {
                 if (!httpExecutor || !pipeline || !assertionEvaluator) {
                     return { error: "HTTP executor not configured" };
                 }
-                const id = args.collection;
-                const result = await store.get(id);
-                if (!result)
-                    return { error: `Collection '${id}' not found` };
-                const { collection } = result;
-                // Resolve environment
-                const envName = args.environment ?? collection.active_environment;
-                if (!envName) {
-                    return { error: "No environment specified and no active_environment set on the collection" };
-                }
-                const environment = collection.environments?.[slugify(envName)];
-                if (!environment) {
-                    return { error: `Environment '${envName}' not found in collection '${id}'` };
+                const loaded = await loadForRun(args);
+                if ("error" in loaded)
+                    return loaded;
+                const runId = typeof args.run_id === "string" && args.run_id ? args.run_id : undefined;
+                const flag = { cancelled: false };
+                if (runId)
+                    activeRuns.set(runId, flag);
+                try {
+                    return await runScenario({
+                        collection: loaded.collection,
+                        collectionId: loaded.id,
+                        scenario: args.scenario,
+                        environment: args.environment,
+                        inputs: args.inputs,
+                        httpExecutor,
+                        pipeline,
+                        assertionEvaluator,
+                        scriptRunner,
+                        isCancelled: () => flag.cancelled,
+                        onEvent: hooks?.onEvent && runId ? (event) => hooks.onEvent({ ...event, run_id: runId }) : undefined,
+                    });
                 }
-                // Find scenario
-                const scenarioKey = args.scenario;
-                const scenario = collection.scenarios?.[scenarioKey];
-                if (!scenario) {
-                    return { error: `Scenario '${scenarioKey}' not found in collection '${id}'` };
+                finally {
+                    if (runId)
+                        activeRuns.delete(runId);
                 }
-                return executeScenario({
-                    scenarioKey,
-                    steps: scenario.steps,
-                    collectionId: id,
-                    collection,
-                    environment,
-                    httpExecutor,
-                    pipeline,
-                    assertionEvaluator,
-                    scriptRunner,
-                });
+            }
+            case "neuron_api_get_run_inputs": {
+                const loaded = await loadForRun(args);
+                if ("error" in loaded)
+                    return loaded;
+                const res = runInputsFor(loaded.collection, loaded.id, args.scenario, args.environment);
+                if ("error" in res)
+                    return res;
+                return { collection: loaded.id, environment: res.environment, scenario: args.scenario ?? null, inputs: res.inputs };
+            }
+            case "neuron_api_cancel_run": {
+                const flag = activeRuns.get(args.run_id);
+                if (!flag)
+                    return { cancelled: false, error: `No active run '${args.run_id}'` };
+                flag.cancelled = true;
+                return { cancelled: true, run_id: args.run_id };
             }
             // ── Query and generation ─────────────────────────────
             case "neuron_api_query": {