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/fingerprint.js

@@ -1,9 +1,17 @@
 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 mergeData(data) {
+  if (data != null && typeof data === "object" && !Array.isArray(data)) {
+    return { ...data };
+  }
+  return {};
 }
 
 async function fingerprint(ctx) {
@@ -28,13 +36,14 @@ async function fingerprint(ctx) {
     maxAge: ctx.config?.maxAge,
   });
 
-  ensureDataObject(ctx);
-  ctx.data.fingerprint = result.hash;
-  ctx.data.fingerprintChanged = result.changed;
-  ctx.data.fingerprintPrevious = result.previous;
-  ctx.data.fingerprintAt = result.changed ? result.at : result.previousAt;
-  ctx.data.fingerprintAge = result.ageMs;
-  ctx.data.fingerprintExpired = result.expired;
+  const extra = {
+    fingerprint: result.hash,
+    fingerprintChanged: result.changed,
+    fingerprintPrevious: result.previous,
+    fingerprintAt: result.changed ? result.at : result.previousAt,
+    fingerprintAge: result.ageMs,
+    fingerprintExpired: result.expired,
+  };
 
   log.info(
     {
@@ -46,17 +55,22 @@ async function fingerprint(ctx) {
     "fingerprint: result",
   );
 
+  /** @type {{ output: Record<string, unknown>, context: Record<string, unknown>, skipRemaining?: true }} */
+  const envelope = {
+    output: { ...mergeData(ctx.data), ...extra },
+    context: { ...passContext(ctx), ...extra },
+  };
   if (!result.changed && skipRemaining) {
-    ctx.skipRemaining = true;
+    envelope.skipRemaining = true;
   }
-
-  return ctx;
+  return envelope;
 }
 
 fingerprint.meta = {
   description:
     "Hash a value, compare it to the last stored fingerprint, and skip remaining steps when unchanged",
   previewConfigKey: "key",
+  reads: "ctx",
   config: {
     key: {
       type: "string",
@@ -88,6 +102,14 @@ fingerprint.meta = {
     fingerprintAge: { type: "number", required: false, description: "Age in milliseconds" },
     fingerprintExpired: { type: "boolean" },
   },
+  context: {
+    fingerprint: { type: "string" },
+    fingerprintChanged: { type: "boolean" },
+    fingerprintPrevious: { type: "string", required: false },
+    fingerprintAt: { type: "string", required: false },
+    fingerprintAge: { type: "number", required: false },
+    fingerprintExpired: { type: "boolean" },
+  },
   example: {
     data: { item: { guid: "https://example.com/post-1" } },
     config: {