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-binary.js

@@ -1,7 +1,15 @@
-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 mergeData(data) {
+  if (data != null && typeof data === "object" && !Array.isArray(data)) {
+    return { ...data };
+  }
+  return {};
 }
 
 function filenameFromUrl(url) {
@@ -38,8 +46,6 @@ function resolveUrl(ctx) {
 }
 
 async function fetchBinary(ctx) {
-  ensureDataObject(ctx);
-
   const url = resolveUrl(ctx);
   if (!url) {
     throw new Error(
@@ -55,27 +61,32 @@ async function fetchBinary(ctx) {
   const response = await $axios.get(url, { responseType: "arraybuffer" });
   const file = Buffer.from(response.data ?? []);
   const contentType = String(response.headers?.["content-type"] ?? "application/octet-stream");
-  const filename = ctx.config?.filename || ctx.data.filename || filenameFromUrl(url);
+  const filename = ctx.config?.filename || ctx.data?.filename || filenameFromUrl(url);
 
-  ctx.data[outputVar] = file;
-  ctx.data.filename = filename;
-  ctx.data.contentType = contentType;
+  const extra = {
+    [outputVar]: file,
+    filename,
+    contentType,
+  };
 
   log.info(
     { outputVar, filename, contentType, length: file.length },
     "fetch-binary: saved",
   );
 
-  return ctx;
+  return {
+    output: { ...mergeData(ctx.data), ...extra },
+    context: { ...passContext(ctx), ...extra },
+  };
 }
 
 fetchBinary.meta = {
-  description: "Download a binary URL into ctx.data as a Buffer",
+  description: "Download a binary URL and add the Buffer to output (keeps previous data fields)",
   previewConfigKey: "url",
   config: {
     url: { type: "string", required: false, description: "Direct download URL" },
     urlVar: { type: "string", required: false, description: "Key in ctx.data that holds the URL" },
-    outputVar: { type: "string", default: "file", description: "ctx.data key for the Buffer" },
+    outputVar: { type: "string", default: "file", description: "output key for the Buffer" },
     filename: { type: "string", required: false, description: "Override saved filename" },
   },
   input: {
@@ -88,6 +99,11 @@ fetchBinary.meta = {
     filename: { type: "string" },
     contentType: { type: "string" },
   },
+  context: {
+    file: { type: "buffer", description: "Downloaded bytes (or ctx.config.outputVar)" },
+    filename: { type: "string" },
+    contentType: { type: "string" },
+  },
   example: {
     data: { attach: "https://example.com/image.png" },
     config: { outputVar: "file" },