@stubber/virtual-worker 1.0.1

package/.env_dev

@@ -0,0 +1,14 @@
+# when running inside docker and connecting to tag running on host machine
+# WORKER_CONNECT_URL=http://172.17.0.1:7450/orgs/7cf3b2dc-5a49-51dd-8b4d-812a8ba6f233
+# when running using npm run dev and connecting to tag running on host machine
+# WORKER_CONNECT_URL=http://localhost:7450/orgs/7cf3b2dc-5a49-51dd-8b4d-812a8ba6f233
+# when used in docker or with npm run, connect to the devmaster tag
+WORKER_CONNECT_URL="https://virtual-workers.dev.stubber.com/orgs/7cf3b2dc-5a49-51dd-8b4d-812a8ba6f233"
+
+WORKER_SIGNATURE=069c293dc0d71dd42b32b122da62b2deae08c12c67a85224d14a7dd8c4907f21
+
+WORKER_WORKERUUID=b0bf29a8-5ebb-4b79-b464-9d35686ebc7d
+
+WORKER_GROUPS=insurance-worker,b0bf29a8-5ebb-4b79-b464-9d35686ebc7d
+
+NODE_ENV=development

package/.env_devmaster

@@ -0,0 +1,7 @@
+WORKER_CONNECT_URL="https://virtual-workers.dev.stubber.com/orgs/7cf3b2dc-5a49-51dd-8b4d-812a8ba6f233"
+
+WORKER_SIGNATURE=069c293dc0d71dd42b32b122da62b2deae08c12c67a85224d14a7dd8c4907f21
+
+WORKER_WORKERUUID=b0bf29a8-5ebb-4b79-b464-9d35686ebc7d
+
+WORKER_GROUPS=insurance-worker,b0bf29a8-5ebb-4b79-b464-9d35686ebc7d

package/.eslintrc.json

@@ -0,0 +1,20 @@
+{
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "extends": "eslint:recommended",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["filenames"],
+  "rules": {
+    "no-unused-vars": "off",
+    "id-match": ["warn", "^_*[a-z0-9]+(_[a-z0-9]+)*$|^_*[A-Z0-9]+(_[A-Z0-9]+)*$|_", { "properties": true }],
+    "filenames/match-regex": ["warn", "^[a-z]+(_[a-z]+)*$", true]
+  },
+  "globals": {
+    "__baseFileNameData": "readonly"
+  }
+}

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "useTabs": false,
+  "tabWidth": 2,
+  "semi": true,
+  "printWidth": 120
+}

package/app/commands/browser/browser_click.js

@@ -0,0 +1,143 @@
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { create_success } from "#app/functions/create_success.js";
+import { get_chromium_page } from "../../helpers/get_chromium_page.js";
+import fs from "fs";
+import { v4 } from "uuid";
+
+/**
+ *
+ * @param {Object} params
+ * @param {Array<{ locator: string, frame?:string, options?: Object, download?: boolean }> } params.entries - Array of entries to click
+ * @returns
+ */
+export const browser_click = async (params, stubber_context) => {
+  // Extract coordinates from options
+  const { entries } = params || {};
+
+  // use playwright to move the mouse and perform a left click
+  const page_result = await get_chromium_page(stubber_context.stubref);
+
+  if (!page_result.success) {
+    return page_result;
+  }
+
+  const page = page_result.payload;
+
+  const downloads = [];
+
+  for (let { locator, frame, options, download } of entries) {
+    if (!locator) {
+      return create_error_conceptual({ message: "Locator is required", details: { locator, frame } });
+    }
+
+    /** @type {import('playwright').Locator} */
+    let target;
+    if (frame) {
+      const frame_handle = page.frameLocator(frame);
+      target = frame_handle.locator(locator);
+    } else {
+      target = page.locator(locator);
+    }
+
+    // const target = page.locator(locator);
+
+    try {
+      await target.waitFor({ state: "attached", timeout: 5000 });
+    } catch {
+      return create_error_conceptual({ message: "No element found for locator", details: { locator, frame } });
+    }
+
+    if (download) {
+      // not all downloads are made equal. Some of them actually trigger the "download" event, in which case playwright handles it
+      // however, some files, like PDFs, are opened inline in the browser, so no download event is triggered
+      // for those, if the user specifies download: true, we will try to fetch the file ourselves
+      const [download_evt, popup_evt] = await Promise.all([
+        page.waitForEvent("download", { timeout: 3000 }).catch(() => null), // don’t throw if no event
+        page.waitForEvent("popup").catch(() => null),
+        target.click(),
+      ]);
+
+      if (download_evt) {
+        const path = await download_evt.path();
+        console.log("Downloaded file path:", path);
+
+        downloads.push({
+          file_name: download_evt.suggestedFilename(),
+          file_path: path,
+          url: download_evt.url(),
+        });
+      } else if (popup_evt) {
+        await popup_evt.waitForLoadState();
+
+        // Fallback: maybe inline PDF
+        const { file_name, file_path, url } = await download_inline_file(popup_evt.url());
+        downloads.push({ url, file_path, file_name });
+        // close the popup to avoid too many open pages
+        await popup_evt.close();
+      } else {
+        throw create_error_conceptual({ message: "No download or popup event detected.", details: { locator, frame } });
+      }
+    } else {
+      // if target is an <option> element, we need to use selectOption instead of click
+      const tag_name = await target.evaluate((el) => el.tagName.toLowerCase());
+      if (tag_name === "option") {
+        const value = await target.evaluate((el) => el.value);
+        const select = target.locator("xpath=..");
+        console.log("Selecting option with value:", value, select);
+        await select.selectOption(value);
+      } else {
+        await target.click(options);
+      }
+    }
+  }
+
+  const payload = {};
+
+  if (downloads.length) {
+    payload.downloads = downloads;
+  }
+
+  return create_success({ message: "Click(s) executed successfully", payload });
+};
+
+/**
+ *
+ * @param {string} url
+ */
+const download_inline_file = async (url) => {
+  // Use Node to fetch directly
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download file: ${response.statusText}`);
+  }
+
+  // try to look at Content-Disposition header first
+  const cd_header = response.headers.get("Content-Disposition");
+  let suggested_filename = null;
+
+  if (cd_header) {
+    const matches = cd_header.match(/filename="?(.+?)"?;?$/);
+    if (matches) {
+      suggested_filename = matches[1];
+    }
+  }
+
+  if (!suggested_filename) {
+    const uri = new URL(url);
+    const pathname = uri.pathname;
+    const last_part = pathname.split("/").pop();
+
+    suggested_filename = last_part || v4();
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+
+  const file_path = `/tmp/${suggested_filename}`; // or configurable download dir
+
+  console.log("Downloaded file path:", file_path);
+
+  fs.writeFileSync(file_path, buffer);
+
+  return { file_name: suggested_filename, file_path, url };
+};

package/app/commands/browser/browser_extract_data.js

@@ -0,0 +1,89 @@
+import { create_success } from "#app/functions/create_success.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { get_chromium_page } from "../../helpers/get_chromium_page.js";
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+
+export const browser_extract_data = async (params, stubber_context) => {
+  if (!params?.locators) {
+    return create_error_conceptual({ message: "No locators provided", details: { params } });
+  }
+
+  // Get the Chromium page
+  const page_result = await get_chromium_page(stubber_context.stubref);
+  if (!page_result.success) {
+    return page_result;
+  }
+
+  const page = page_result.payload;
+  // object with deeply nested properties, each string property is a locator to a dom element/s
+  const payload_locators = params?.locators;
+
+  const payload = await get_payload_from_dom(page, payload_locators);
+
+  return create_success(`DOM content retrieved successfully`, payload);
+};
+
+/** * Recursively retrieves data from the DOM based on the provided locators.
+ * @param {import("playwright").Page} page - The Playwright page object.
+ * @param {object|string} locators - The locators to use for extracting data.
+ * @param {import("playwright").Locator} [root=page] - The root locator to start from.
+ */
+const get_payload_from_dom = async (page, locators, root = page) => {
+  // Handle string case directly
+  if (typeof locators === "string") {
+    const target = root.locator(locators);
+
+    return (await target.count()) ? await target.innerText() : null;
+  } else if (typeof locators === "object" && locators !== null && !Array.isArray(locators)) {
+    const is_list = "_list" in locators && "_list_item_properties" in locators;
+    if (is_list) {
+      // Handle list case
+      const elements = root.locator(locators._list);
+      const count = await elements.count();
+      const items = [];
+
+      for (let i = 0; i < count; i++) {
+        const element_handle = elements.nth(i);
+        const item = await get_payload_from_dom(page, locators._list_item_properties, element_handle);
+        items.push(item);
+      }
+
+      return items; // Return the array of items
+    }
+
+    const is_locator = "_locator" in locators;
+    if (is_locator) {
+      return await get_payload_from_locator(root, locators);
+    }
+
+    const result = {};
+    for (const [key, locator] of Object.entries(locators)) {
+      //recursively handle nested locators
+      result[key] = await get_payload_from_dom(page, locator, root);
+    }
+    return result; // Return the object with nested locators resolved
+  } else {
+    return null; // Return null if locators is neither a string nor an object
+  }
+};
+
+/**
+ * @typedef {"innertText"|"innerHTML"|"href"|"id"} TargetProperty
+ */
+
+/**
+ * @param {import("playwright").Locator} root
+ * @param {{_locator: string, _target: TargetProperty}} locator - The locator object containing the properties to extract.
+ */
+const get_payload_from_locator = async (root, locator) => {
+  const target = root.locator(locator._locator);
+  switch (locator._target) {
+    case "innerText":
+      return (await target.count()) ? await target.innerText() : null;
+    case "innerHTML":
+      return (await target.count()) ? await target.innerHTML() : null;
+    default:
+      // return (await target.count()) ? await target.getAttribute("id") : null;
+      return (await target.count()) ? await target.getAttribute(locator._target) : null;
+  }
+};

package/app/commands/browser/browser_get_localstorage.js

@@ -0,0 +1,27 @@
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { create_success } from "#app/functions/create_success.js";
+import { get_chromium_page } from "../../helpers/get_chromium_page.js";
+
+export const browser_get_localstorage = async (param, stubber_context) => {
+  const page_result = await get_chromium_page(stubber_context.stubref);
+
+  if (!page_result.success) {
+    return page_result;
+  }
+
+  const page = page_result.payload;
+
+  const page_url = page.url();
+
+  if (!page_url || page_url === "about:blank") {
+    return create_error_conceptual({ message: "No page loaded", details: { url: page_url } });
+  }
+
+  const localstorage = await page.evaluate(() => {
+    /* global localStorage */
+    return localStorage;
+  });
+
+  return create_success({ message: "Local storage retrieved successfully", payload: localstorage });
+};

package/app/commands/browser/browser_navigate.js

@@ -0,0 +1,18 @@
+// eslint-disable-next-line id-match
+import { create_success } from "#app/functions/create_success.js";
+import { get_chromium_page } from "../../helpers/get_chromium_page.js";
+
+export const browser_navigate = async (params, stubber_context) => {
+  const result = await get_chromium_page(stubber_context.stubref);
+  if (!result.success) {
+    return result;
+  }
+
+  const { url } = params || {};
+
+  const page = result.payload;
+
+  if (url) await page.goto(url);
+
+  return create_success({ message: "Navigated to new page", payload: {} });
+};

package/app/commands/browser/browser_press_key.js

@@ -0,0 +1,58 @@
+import { create_success } from "#app/functions/create_success.js";
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { get_chromium_page } from "#app/helpers/get_chromium_page.js";
+
+/**
+ *
+ * @param {Object} params
+ * @param {Array<{locator?: string, frame?:string, key?: string, keys?: string}>} params.entries - Array of locator and key pairs.
+ * @returns
+ */
+export const browser_press_key = async ({ entries }, stubber_context) => {
+  const page_result = await get_chromium_page(stubber_context.stubref);
+  if (!page_result.success) {
+    return page_result;
+  }
+  const page = page_result.payload;
+
+  for (let { locator, frame, key, keys } of entries) {
+    if (!key && !keys) {
+      return create_error_conceptual({ message: "'key' or 'keys' is required", details: { locator, key, keys } });
+    }
+
+    if (key) {
+      key = key.toString();
+    }
+
+    if (!locator) {
+      if (key) {
+        await page.keyboard.press(key);
+      } else if (keys) {
+        await page.keyboard.type(keys);
+      }
+      continue; // If no locator is provided, just press the key on the page
+    }
+
+    /** @type {import('playwright').Locator} */
+    let target;
+    if (frame) {
+      const frame_handle = page.frameLocator(frame);
+      target = frame_handle.locator(locator);
+    } else {
+      target = page.locator(locator);
+    }
+
+    if (!(await target.count())) {
+      return create_error_conceptual({ message: "No element found for locator", details: { locator, key, keys } });
+    }
+
+    if (key) {
+      await target.press(key);
+    } else if (keys) {
+      await target.pressSequentially(keys);
+    }
+  }
+
+  return create_success({ message: "Key(s) pressed successfully", payload: {} });
+};

package/app/commands/browser/browser_write_text.js

@@ -0,0 +1,51 @@
+import { create_success } from "#app/functions/create_success.js";
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { get_chromium_page } from "../../helpers/get_chromium_page.js";
+
+/**
+ *
+ * @param {Object} params
+ * @param {Array<{locator: string, frame?:string, text: string}>} params.entries - Array of locator and text pairs.
+ * @returns
+ */
+export const browser_write_text = async ({ entries }, stubber_context) => {
+  const page_result = await get_chromium_page(stubber_context.stubref);
+  if (!page_result.success) {
+    return page_result;
+  }
+  const page = page_result.payload;
+
+  for (let { locator, frame, text } of entries) {
+    if (!locator) {
+      return create_error_conceptual({ message: "Locator is required", details: { locator, text } });
+    }
+
+    if (!text) {
+      return create_error_conceptual({ message: "Text is required", details: { locator, text } });
+    }
+
+    text = text.toString();
+
+    if (typeof text !== "string" || text.trim() === "") {
+      return create_error_conceptual({ message: "Text must be a non-empty string", details: { locator, text } });
+    }
+
+    /** @type {import('playwright').Locator} */
+    let target;
+    if (frame) {
+      const frame_handle = page.frameLocator(frame);
+      target = frame_handle.locator(locator);
+    } else {
+      target = page.locator(locator);
+    }
+
+    if (!(await target.count())) {
+      return create_error_conceptual({ message: "No element found for locator", details: { locator, text } });
+    }
+
+    await target.fill(text);
+  }
+
+  return create_success({ message: "Text written successfully", payload: {} });
+};

package/app/commands/cli/cli_run.js

@@ -0,0 +1,56 @@
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { create_success } from "#app/functions/create_success.js";
+import { exec as exec_cb } from "node:child_process";
+import { promisify } from "node:util";
+
+const exec = promisify(exec_cb);
+
+/**
+ * Run an arbitrary CLI command and return stdout/stderr.
+ * @param {{command: string, timeout?: number, cwd?: string, env?: Object, max_buffer?: number}} params
+ */
+export const cli_run = async (params, _stubber) => {
+  const { command, timeout, cwd, env, max_buffer } = params || {};
+
+  if (!command || typeof command !== "string") {
+    return create_error_conceptual({
+      message: "Command parameter is required and must be a string",
+      details: { params },
+    });
+  }
+
+  try {
+    /** @type {import("child_process").ExecOptionsWithStringEncoding} */
+    const options = {
+      // eslint-disable-next-line id-match
+      maxBuffer: 10 * 1024 * 1024,
+    };
+
+    if (typeof timeout === "number") options.timeout = timeout;
+
+    if (cwd) options.cwd = cwd;
+
+    if (env && typeof env === "object") options.env = { ...process.env, ...env };
+
+    // eslint-disable-next-line id-match
+    if (typeof max_buffer === "number") options.maxBuffer = max_buffer;
+
+    const { stdout, stderr } = await exec(command, options);
+
+    return create_success({
+      message: "Command executed successfully",
+      payload: { stdout: String(stdout), stderr: String(stderr) },
+    });
+  } catch (error) {
+    // if exec failed (non-zero exit code or other), include stdout/stderr when available
+    try {
+      if (error && error.stdout) error.stdout = String(error.stdout);
+      if (error && error.stderr) error.stderr = String(error.stderr);
+    } catch (e) {
+      // ignore
+    }
+
+    return create_error_technical(error);
+  }
+};

package/app/commands/file-server/download_files.js

@@ -0,0 +1,80 @@
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { create_success } from "#app/functions/create_success.js";
+// eslint-disable-next-line id-match
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * @typedef DownloadFilesParams
+ * @property {Array<string|{fileuuid:string}>} files - The files to download
+ */
+
+/**
+ * @typedef ResponseFile
+ * @property {string} fileuuid - The UUID of the file
+ * @property {boolean} status - The status of the file download
+ * @property {Buffer<ArrayBuffer>} data - The file data
+ */
+
+/**
+ *
+ * @param {DownloadFilesParams} params
+ */
+export const download_files = async (params, _stubber) => {
+  // todo: how will fileserver work now that we dont have sockets
+  const socket = _stubber?.stubber_context.socket;
+  if (!socket) {
+    return create_error_conceptual({ message: "Socket not available", details: {} });
+  }
+
+  const { files } = params || {};
+  if (!files) {
+    return create_error_conceptual({ message: "Files parameter is required", details: { params } });
+  }
+  if (!Array.isArray(files) || files.length === 0) {
+    return create_error_conceptual({ message: "Files must be a non-empty array", details: { files } });
+  }
+
+  const uuids = [];
+  for (const file of files) {
+    if (typeof file === "string") {
+      uuids.push(file);
+    } else if (file && typeof file === "object" && typeof file.fileuuid === "string") {
+      uuids.push(file.fileuuid);
+    } else {
+      return create_error_conceptual({ message: "Invalid file entry in files array", details: { entry: file } });
+    }
+  }
+
+  return new Promise((resolve) => {
+    const downloaded_files = [];
+
+    socket.emit("download_files", uuids, async (response) => {
+      if (response.success) {
+        /** @type {ResponseFile[]} */
+        const files = response.payload;
+
+        for (const file of files) {
+          if (file.status == 200) {
+            // todo: support passing download location in params
+            const tmp_dir = tmpdir();
+            const file_path = join(tmp_dir, file.fileuuid);
+
+            await writeFile(file_path, file.data);
+
+            downloaded_files.push(file_path);
+          } else {
+            console.log("Error downloading file:", file);
+          }
+        }
+
+        resolve(create_success({ message: "Files downloaded successfully", payload: { downloaded_files } }));
+      } else {
+        console.log("Error downloading files:", response.error);
+        resolve(create_error_technical(response.error));
+      }
+    });
+  });
+};

package/app/commands/file-server/upload_files.js

@@ -0,0 +1,57 @@
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { create_success } from "#app/functions/create_success.js";
+// eslint-disable-next-line id-match
+import { readFile } from "node:fs/promises";
+
+/**
+ * Upload files to the server
+ * @param {Object} params - The parameters for the upload
+ * @param {Array<string>} params.files - The path to files to upload
+ */
+export const upload_files = async (params, _stubber) => {
+  /** @type {import("socket.io-client").Socket} */
+  const socket = _stubber?.stubber_context.socket;
+  if (!socket) {
+    return create_error_conceptual({ message: "Socket not available", details: {} });
+  }
+
+  const { files } = params || {};
+  if (!files || !Array.isArray(files)) {
+    return create_error_conceptual({
+      message: "Files parameter is required and must be an array",
+      details: { params },
+    });
+  }
+
+  const uploaded_files = [];
+
+  for (const filepath of files) {
+    const filename = filepath.split("/").pop();
+    const file = await readFile(filepath); // Buffer
+
+    // Wrap socket.emit in a promise so we can await it
+    const file_info = await emit_upload(socket, { filepath, filename }, file);
+
+    if (file_info) {
+      uploaded_files.push(file_info);
+    }
+  }
+
+  return create_success({ message: "Files uploaded successfully", payload: { uploaded_files } });
+};
+
+/**
+ * Wraps a socket.emit call in a Promise
+ */
+function emit_upload(socket, metadata, buffer) {
+  return new Promise((resolve, reject) => {
+    socket.emit("upload_file", metadata, buffer, (response) => {
+      if (!response.success) {
+        reject(new Error(response));
+      } else {
+        resolve(response.payload);
+      }
+    });
+  });
+}

package/app/commands/index.js

@@ -0,0 +1,26 @@
+import { browser_click } from "./browser/browser_click.js";
+import { browser_extract_data } from "./browser/browser_extract_data.js";
+import { browser_get_localstorage } from "./browser/browser_get_localstorage.js";
+import { browser_navigate } from "./browser/browser_navigate.js";
+import { browser_write_text } from "./browser/browser_write_text.js";
+import { browser_press_key } from "./browser/browser_press_key.js";
+import { cli_run } from "./cli/cli_run.js";
+
+import { upload_files } from "./file-server/upload_files.js";
+import { download_files } from "./file-server/download_files.js";
+
+const all_commands = {
+  browser_click,
+  browser_extract_data,
+  browser_get_localstorage,
+  browser_navigate,
+  browser_write_text,
+  browser_press_key,
+
+  cli_run,
+
+  upload_files,
+  download_files,
+};
+
+export { all_commands };

package/app/commands/run_commands.js

@@ -0,0 +1,114 @@
+import jsonata from "jsonata";
+// eslint-disable-next-line id-match
+import { cloneDeep } from "lodash-es";
+import { all_commands } from "./index.js";
+import { create_success } from "#app/functions/create_success.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+
+/**
+ * @typedef {object} Command
+ * @property {string} commandtype - The type of command to run.
+ * @property {object} [params] - The parameters for the command.
+ * @property {bool} [continue_on_error] - Whether to continue on error.
+ * @property {number} [__order] - The order in which to run the command.
+ * @property {string[]} [conditions] - Array of jsonata conditions to evaluate.
+ */
+
+/**
+ * @param {{[key: string]: Command}} commands
+ * @param {object} _stubber - The context this task is being ran in.
+ */
+export const run_commands = async (task, _stubber) => {
+  const commands = task.params?.commands;
+
+  const command_entries = Object.entries(commands).sort((a, b) => {
+    // Sort commands by their __order key, if it exists
+    return (a[1].__order || 0) - (b[1].__order || 0);
+  });
+
+  const payload = {
+    commands: {},
+  };
+
+  const action_context = _stubber.stubber_context || { stubpost: { tasks: {} } };
+  const cloned_context = cloneDeep(action_context);
+  // update the stubber_context on the fly as commands are executed
+  cloned_context.stubpost.tasks[task.task_name] = { payload };
+  cloned_context.commands = payload.commands;
+
+  let important_command_failed = false;
+  for (const [command_name, command] of command_entries) {
+    console.log(`Starting command: ${command_name}`, command);
+
+    // Check if the command has conditions and evaluate them
+    const conditions_met = await evaluate_command_conditions(command, cloned_context);
+    if (!conditions_met) {
+      console.log(`Skipping command ${command_name} due to unmet conditions.`);
+      payload.commands[command_name] = create_success({
+        message: "Command skipped due to conditions not met",
+        details: {
+          conditions: command.conditions,
+        },
+      });
+      continue; // Skip this command if conditions are not met
+    }
+
+    const commandtype = command.commandtype;
+
+    const command_function = all_commands[commandtype];
+    if (!command_function) {
+      payload.commands[command_name] = create_error_conceptual({
+        message: `Command function not found for command type: ${commandtype}`,
+        details: { command },
+      });
+    } else {
+      try {
+        payload.commands[command_name] = await command_function(command.params, _stubber);
+      } catch (error) {
+        console.error(`Error running command ${command_name}:`, error);
+        payload.commands[command_name] = create_error_technical(error);
+      }
+    }
+
+    if (!payload.commands[command_name].success && !command.continue_on_error) {
+      important_command_failed = true;
+      break; // Stop execution if continue_on_error is falsy
+    }
+  }
+
+  if (important_command_failed) {
+    return create_error_conceptual({
+      message: "Some commands failed",
+      details: { ...payload },
+    });
+  }
+
+  return create_success({ message: "All commands executed successfully", payload });
+};
+
+/**
+ * @param {Command} command
+ * @param {object} context
+ */
+const evaluate_command_conditions = async (command, context) => {
+  if (!command.conditions || Array.isArray(command.conditions) === false) {
+    return true; // No conditions to evaluate, so we consider it true
+  }
+
+  for (let condition of command.conditions) {
+    if (typeof condition !== "string") {
+      condition = JSON.stringify(condition);
+    }
+
+    const expression = jsonata(condition);
+
+    const result = await expression.evaluate(context);
+
+    if (!result) {
+      return false;
+    }
+  }
+
+  return true;
+};

package/app/controllers/virtual_worker_status.js

@@ -0,0 +1,20 @@
+import { create_success } from "#app/functions/create_success.js";
+import { task_schema } from "#lib/interfaces/http/routers/stubber_task_schema.js";
+
+/** @type {{ last_task_received: Date|null }} */
+export let worker_status = {
+  last_task_received: null,
+};
+
+/**
+ *
+ * @param {z.infer<typeof task_schema>} task
+ */
+export const virtual_worker_status = async (task) => {
+  return create_success({
+    message: "Virtual worker is operational",
+    payload: {
+      last_task_received: worker_status.last_task_received?.toISOString(),
+    },
+  });
+};

package/app/controllers/virtual_worker_task.js

@@ -0,0 +1,34 @@
+import { run_commands } from "#app/commands/run_commands.js";
+import { task_schema } from "#lib/interfaces/http/routers/stubber_task_schema.js";
+import * as z from "zod";
+import { worker_status } from "./virtual_worker_status.js";
+
+const command_schema = z.object({
+  commandtype: z.string().min(1),
+  params: z.record(z.string(), z.any()).optional(),
+  continue_on_error: z.boolean().optional(),
+  __order: z.number().optional(),
+  conditions: z.array(z.string()).optional(),
+});
+
+const params_schema = z.object({
+  commands: z.record(z.string(), command_schema),
+  worker: z.object({
+    group: z.string().min(1),
+  }),
+});
+
+/**
+ *
+ * @param {z.infer<typeof task_schema>} task
+ */
+export const virtual_worker_task = async (task) => {
+  worker_status.last_task_received = new Date();
+
+  const stubber = task._stubber;
+  task.params = params_schema.parse(task.params);
+
+  const task_result = await run_commands(task, stubber);
+
+  return task_result;
+};

package/app/functions/create_error_conceptual.js

@@ -0,0 +1,12 @@
+export const create_error_conceptual = ({ message, details = {} }) => {
+  console.warn("Conceptual Error:", message, details);
+
+  return {
+    success: false,
+    message: message || "An error occurred",
+    error: {
+      type: "conceptual",
+      details: details,
+    },
+  };
+};

package/app/functions/create_error_technical.js

@@ -0,0 +1,18 @@
+/**
+ * @param {Error} error
+ */
+export const create_error_technical = (error) => {
+  console.error("Technical error:", error);
+  return {
+    success: false,
+    message: error.message || "An error occurred",
+    error: {
+      type: "technical",
+      details: {
+        name: error.name,
+        // stack up to the second \n newline
+        stack: error.stack.split("\n").slice(0, 2).join("\n"),
+      },
+    },
+  };
+};

package/app/functions/create_success.js

@@ -0,0 +1,7 @@
+export const create_success = ({ message, payload = {} }) => {
+  return {
+    success: true,
+    message: message || "Operation completed successfully",
+    payload: payload,
+  };
+};

package/app/helpers/get_chromium_page.js

@@ -0,0 +1,72 @@
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+import { create_success } from "#app/functions/create_success.js";
+import { chromium } from "playwright";
+
+/** @type {import("playwright").Browser} */
+let browser;
+
+/** @type {Record<string, {
+ * context: import("playwright").BrowserContext,
+ * last_used: number
+}>} */
+const contexts = {};
+const CONTEXT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * @param {string} stubref
+ * @returns {Promise<{ success: boolean, payload?: import("playwright").Page }>}
+ */
+export const get_chromium_page = async (stubref) => {
+  if (!stubref) {
+    return create_error_conceptual({ message: "stubref is required to get a Chromium page." });
+  }
+
+  // Cleanup unused contexts
+  const now = Date.now();
+  for (const [key, value] of Object.entries(contexts)) {
+    if (value.last_used && now - value.last_used > CONTEXT_TIMEOUT_MS) {
+      try {
+        await value.context.close();
+      } catch (e) {
+        // ignore errors during cleanup
+      }
+      delete contexts[key];
+    }
+  }
+
+  // Launch the browser once and reuse it
+  if (!browser) {
+    browser = await chromium.launch({
+      headless: false,
+      // eslint-disable-next-line id-match
+      slowMo: 1500,
+    });
+  }
+
+  // Create a new context per stubref if not already created
+  if (!contexts[stubref]) {
+    const context = await browser.newContext({
+      // eslint-disable-next-line id-match
+      ignoreHTTPSErrors: true,
+    });
+    contexts[stubref] = {
+      context,
+      last_used: now,
+    };
+  } else {
+    contexts[stubref].last_used = now;
+  }
+
+  const context = contexts[stubref].context;
+
+  // Try to find an open page in the context
+  let page = context.pages().find((p) => !p.isClosed());
+
+  // If no open page, create a new one
+  if (!page) {
+    page = await context.newPage();
+  }
+
+  return create_success({ message: "Successfully retrieved Chromium page.", payload: page });
+};

package/app.js

@@ -0,0 +1,4 @@
+import "dotenv/config"; // see https://github.com/motdotla/dotenv#how-do-i-use-dotenv-with-import
+import { start_http_server } from "#lib/interfaces/http/index.js";
+
+start_http_server();

package/app_config.js

@@ -0,0 +1,6 @@
+export const config = {
+  WORKER_CONNECT_URL: process.env.WORKER_CONNECT_URL,
+  WORKER_SIGNATURE: process.env.WORKER_SIGNATURE,
+  WORKER_WORKERUUID: process.env.WORKER_WORKERUUID,
+  WORKER_GROUPS: process.env.WORKER_GROUPS?.split(",") || [],
+};

package/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { start_http_server } from "#lib/interfaces/http/index.js";
+
+start_http_server();

package/devel/client_vnc_agent.js

@@ -0,0 +1,29 @@
+// client-vnc-agent.js
+import io from "socket.io-client";
+import net from "net";
+
+const socket = io("ws://localhost:7450", {
+  path: "/tunnel",
+  transports: ["websocket"],
+});
+
+socket.on("connect", () => {
+  console.log("Connected to tunnel server");
+  const vncSocket = net.createConnection({ host: "localhost", port: 5900 });
+
+  vncSocket.on("data", (data) => {
+    socket.emit("vnc-data", data);
+  });
+
+  vncSocket.on("close", () => {
+    socket.disconnect();
+  });
+
+  socket.on("vnc-data", (b64) => {
+    vncSocket.write(b64);
+  });
+
+  socket.on("disconnect", () => {
+    vncSocket.end();
+  });
+});

package/lib/interfaces/http/index.js

@@ -0,0 +1,23 @@
+import body_parser from "body-parser";
+import express from "express";
+import task_gateway_router from "./routers/task_gateway.js";
+import { virtual_worker_status } from "#root/app/controllers/virtual_worker_status.js";
+
+export const start_http_server = () => {
+  const app = express();
+  app.use(body_parser.json());
+
+  // ROUTERS
+  app.use("/api/v1/task-gateway", task_gateway_router);
+
+  // health check endpoint
+  app.get("/api/v1/health", async (req, res) => {
+    const worker_status = await virtual_worker_status({});
+    res.status(200).json(worker_status);
+  });
+
+  const PORT = process.env.HTTP_PORT || 3000;
+  app.listen(PORT, () => {
+    console.log(`HTTP server is running on port ${PORT}`);
+  });
+};

package/lib/interfaces/http/routers/stubber_task_schema.js

@@ -0,0 +1,16 @@
+import * as z from "zod";
+
+export const stubber_schema = z.object({
+  orguuid: z.uuid(),
+});
+
+export const task_schema = z.object({
+  tasktype: z.string().min(1),
+  task_name: z.string().min(1),
+  params: z.any(),
+  _stubber: stubber_schema,
+});
+
+export const task_payload_schema = z.object({
+  task: task_schema,
+});

package/lib/interfaces/http/routers/task_gateway.js

@@ -0,0 +1,49 @@
+import { virtual_worker_task } from "#app/controllers/virtual_worker_task.js";
+import { create_error_conceptual } from "#app/functions/create_error_conceptual.js";
+import { create_error_technical } from "#app/functions/create_error_technical.js";
+// eslint-disable-next-line id-match
+import { Router } from "express";
+import * as z from "zod";
+import { task_payload_schema } from "./stubber_task_schema.js";
+import { virtual_worker_status } from "#root/app/controllers/virtual_worker_status.js";
+
+const router = Router();
+
+router.post("/virtual_worker_task", async (req, res) => {
+  try {
+    const payload = task_payload_schema.parse(req.body);
+    const task = payload.task;
+
+    console.log("Received task:", task.task_name, "of type:", task.tasktype, "with params:", task.params);
+
+    const result = await virtual_worker_task(task);
+
+    if (result.success) {
+      res.status(200).json(result);
+    } else {
+      res.status(400).json(result);
+    }
+  } catch (error) {
+    // handle zod validation errors
+    if (error instanceof z.ZodError) {
+      // console.log("Zod validation error:", error);
+      res.status(400).json(
+        create_error_conceptual({
+          message: "Validation error",
+          details: {
+            errors: JSON.parse(error.message),
+          },
+        })
+      );
+    } else {
+      res.status(500).json(create_error_technical(error));
+    }
+  }
+});
+
+router.post("/virtual_worker_status", async (req, res) => {
+  const result = await virtual_worker_status({});
+  res.status(200).json(result);
+});
+
+export default router;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@stubber/virtual-worker",
+  "version": "1.0.1",
+  "description": "Template to easily create a node app and keep development standards",
+  "main": "app.js",
+  "directories": {
+    "lib": "lib",
+    "test": "test"
+  },
+  "bin": {
+    "stubber-virtual-worker": "./cli.js"
+  },
+  "type": "module",
+  "imports": {
+    "#lib/*.js": "./lib/*.js",
+    "#root/*.js": "./*.js",
+    "#app/*.js": "./app/*.js"
+  },
+  "scripts": {
+    "dev": "nodemon app.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stubber/stubber-virtual-worker.git"
+  },
+  "author": "Stubber",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/stubber/stubber-virtual-worker/issues"
+  },
+  "homepage": "https://github.com/stubber/stubber-virtual-worker#readme",
+  "dependencies": {
+    "body-parser": "^1.20.3",
+    "dotenv": "^16.0.3",
+    "express": "^4.18.2",
+    "jsonata": "^2.1.0",
+    "lodash-es": "^4.17.21",
+    "net": "^1.0.2",
+    "playwright": "^1.53.0",
+    "socket.io-client": "^4.8.1",
+    "uuid": "^9.0.0",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "eslint": "^8.56.0",
+    "eslint-plugin-filenames": "^1.3.2",
+    "nodemon": "^3.1.10"
+  }
+}

package/requirements.txt

@@ -0,0 +1,5 @@
+pandas
+openpyxl
+odfpy
+numpy
+xlsxwriter