feat(scripts): enhance script return structure and context handling

- Introduced a new contract for script returns, requiring an object with `output`, `context`, and `skipRemaining` fields.
- Refactored existing scripts to align with the new return structure, ensuring compatibility with the updated context management.
- Added utility functions for normalizing context and step results, improving the handling of script execution context.
- Updated various scripts (e.g., fetch-binary, fetch-html, fetch-http) to return structured output and context, enhancing data flow and usability.
- Improved error handling for script returns, ensuring clearer feedback when invalid structures are returned.

This update significantly enhances the flexibility and clarity of script interactions within workflows.

packages/server/scripts/fetch-html.js

@@ -1,10 +1,11 @@
 import { parse } from "node-html-parser";
 import jsonata from "jsonata";
 
-function ensureDataObject(ctx) {
-  if (ctx.data == null || typeof ctx.data !== "object" || Array.isArray(ctx.data)) {
-    ctx.data = {};
+function passContext(ctx) {
+  if (ctx?.context != null && typeof ctx.context === "object" && !Array.isArray(ctx.context)) {
+    return { ...ctx.context };
   }
+  return {};
 }
 
 function serializeElement(el) {
@@ -43,8 +44,6 @@ async function fetchHtml(ctx) {
     throw new Error("fetch-html: ctx.config.outputVar is required when selector or jsonata is set");
   }
 
-  ensureDataObject(ctx);
-
   log.info({ url }, "fetch-html: fetching page");
   const response = await $axios.get(url);
   log.info(
@@ -52,19 +51,20 @@ async function fetchHtml(ctx) {
     "fetch-html: fetch complete",
   );
 
-  ctx.data.httpResponse = String(response.data ?? "");
+  /** @type {Record<string, unknown>} */
+  const output = { httpResponse: String(response.data ?? "") };
   log.info(
-    { length: ctx.data.httpResponse.length },
+    { length: String(output.httpResponse).length },
     "fetch-html: saved httpResponse",
   );
 
   if (selector) {
     log.info({ selector, outputVar }, "fetch-html: selecting elements");
-    const root = parse(ctx.data.httpResponse);
+    const root = parse(String(output.httpResponse));
     const elements = root.querySelectorAll(selector);
-    ctx.data[outputVar] = elements.map(serializeElement);
+    output[outputVar] = elements.map(serializeElement);
     log.info(
-      { outputVar, count: ctx.data[outputVar].length },
+      { outputVar, count: output[outputVar].length },
       "fetch-html: saved selector matches",
     );
   }
@@ -72,16 +72,15 @@ async function fetchHtml(ctx) {
   if (jsonataExpr) {
     log.info({ outputVar, jsonata: jsonataExpr }, "fetch-html: evaluating jsonata");
     const expression = jsonata(jsonataExpr);
-    const input = ctx.data[outputVar];
-    const result = await expression.evaluate(input);
-    ctx.data[outputVar] = result;
+    const result = await expression.evaluate(output[outputVar]);
+    output[outputVar] = result;
     log.info(
       { outputVar, result: previewValue(result) },
       "fetch-html: saved jsonata result",
     );
   }
 
-  return ctx;
+  return { output, context: { ...passContext(ctx), ...output } };
 }
 
 fetchHtml.meta = {
@@ -100,7 +99,10 @@ fetchHtml.meta = {
   },
   input: {},
   output: {
-    httpResponse: { type: "string", description: "Raw HTML" },
+    httpResponse: { type: "string", description: "Raw HTML (overwritten when outputVar is httpResponse)" },
+  },
+  context: {
+    httpResponse: { type: "any", description: "Same keys as output" },
   },
   example: {
     data: {},