@testdriverai/agent 7.8.0-test.38

package/agent/lib/config.js

@@ -0,0 +1,60 @@
+/**
+ * This file contains application config factory.
+ * It is responsible for creating config instances from environment variables,
+ * supplying defaults, and formatting values
+ */
+
+// Parse out true and false string values
+function parseValue(value) {
+  if (typeof value === "string") {
+    const normalizedValue = value.toLowerCase().trim();
+    if (["true", "false"].includes(normalizedValue)) {
+      return JSON.parse(normalizedValue);
+    }
+  }
+
+  return value;
+}
+
+const channelConfig = require("../../lib/resolve-channel.js");
+
+// Factory function that creates a config instance
+const createConfig = (environment = {}) => {
+  // Start with defaults
+  const config = {
+    TD_ANALYTICS: true,
+    TD_API_ROOT: channelConfig.channels[channelConfig.active],
+    TD_API_KEY: null,
+    TD_PROFILE: false,
+    TD_RESOLUTION: [1366, 768],
+  };
+
+  // Store the full environment for interpolation purposes
+  config._environment = environment;
+
+  // Find all env vars starting with TD_
+  for (let key in environment) {
+    if (key == "TD_RESOLUTION") {
+      config[key] = environment[key].split("x").map((x) => parseInt(x.trim()));
+      continue;
+    }
+
+    if (key.startsWith("TD_")) {
+      config[key] = parseValue(environment[key]);
+    }
+  }
+
+  // Add support for CI environment variable
+  if (environment.CI) {
+    config.CI = parseValue(environment.CI);
+  }
+
+  return config;
+};
+
+// Create a default config instance for backward compatibility
+const defaultConfig = createConfig(process.env);
+
+// Export both the factory function and the default instance
+module.exports = defaultConfig;
+module.exports.createConfig = createConfig;

package/agent/lib/generator.js

@@ -0,0 +1,91 @@
+// parses markdown content to find code blocks, and then extracts yaml from those code blocks
+const yaml = require("js-yaml");
+const pkg = require("../../package.json");
+const session = require("./session");
+const theme = require("./theme");
+// do the actual parsing
+// this library is very strict
+// note that errors are sent to the AI will it may self-heal
+const manualToYml = async function (inputArgs) {
+  // input is like `command=click x=100 y=200 z='this is a string'`
+  // convert this to json
+
+  const pattern = /(\w+)=('[^']*'|[^\s]+)/g;
+
+  let match;
+  let json = {};
+
+  while ((match = pattern.exec(inputArgs)) !== null) {
+    const key = match[1];
+    const value = match[2].replace(/'/g, ""); // Remove single quotes if present
+    json[key] = value;
+  }
+
+  json = {
+    commands: [json],
+  };
+
+  // use yml dump to convert json to yml
+  let yml = await yaml.dump(json);
+
+  return yml;
+};
+
+const jsonToManual = function (json, colors = true) {
+  // Convert the JSON object to key-value pairs
+  const params = Object.keys(json)
+    .map((key) => {
+      let value = json[key];
+
+      // If the value contains spaces, wrap it in single quotes
+      if (typeof value === "string") {
+        value = `'${value}'`;
+      }
+
+      if (colors) {
+        return `${theme.cyan(key)}=${theme.green(value)}`;
+      } else {
+        return `${key}=${value}`;
+      }
+    })
+    .join(" ");
+
+  return params;
+};
+
+const dumpToYML = async function (inputArray, sessionInstance = null) {
+  // use yml dump to convert json to yml
+  let yml = await yaml.dump({
+    version: pkg.version,
+    session: sessionInstance ? sessionInstance.get() : session.get(),
+    steps: inputArray,
+  });
+
+  return yml;
+};
+
+const hydrateFromYML = async function (yml, sessionInstance = null) {
+  // use yml load to convert yml to json
+  let json = await yaml.load(yml);
+
+  if (!json) {
+    json = {};
+  }
+
+  const sessionToUse = sessionInstance || session;
+
+  if (!json?.session) {
+    json.session = sessionToUse.get();
+  }
+
+  sessionToUse.set(json.session);
+
+  return json;
+};
+
+module.exports = {
+  manualToYml,
+  dumpToYML,
+  hydrateFromYML,
+  jsonToManual,
+};

package/agent/lib/http.js

@@ -0,0 +1,144 @@
+/**
+ * Shared HTTP client for the TestDriver SDK.
+ *
+ * All SDK HTTP traffic should go through these helpers so that
+ * User-Agent, timeouts, Sentry tracing headers, and response
+ * parsing are handled in one place.
+ *
+ * Uses axios under the hood — the same library the rest of the SDK
+ * already depends on.
+ */
+
+const axios = require("axios");
+const crypto = require("crypto");
+const { version } = require("../../package.json");
+
+const USER_AGENT = `TestDriverSDK/${version} (Node.js ${process.version})`;
+
+/**
+ * Generate Sentry distributed-tracing headers from a session ID.
+ * Both sandbox.js and sdk.js duplicated this — it now lives here.
+ *
+ * @param {string} sessionId
+ * @returns {object} Headers object (empty if no sessionId)
+ */
+function getSentryTraceHeaders(sessionId) {
+  if (!sessionId) return {};
+  const traceId = crypto.createHash("md5").update(sessionId).digest("hex");
+  const spanId = crypto.randomBytes(8).toString("hex");
+  return {
+    "sentry-trace": traceId + "-" + spanId + "-1",
+    baggage:
+      "sentry-trace_id=" +
+      traceId +
+      ",sentry-sample_rate=1.0,sentry-sampled=true",
+  };
+}
+
+/**
+ * Build common request headers.
+ * @param {object} [extra] - Additional headers to merge
+ * @returns {object}
+ */
+function baseHeaders(extra) {
+  return {
+    "User-Agent": USER_AGENT,
+    ...extra,
+  };
+}
+
+/**
+ * POST JSON to `url` and return the parsed response body.
+ *
+ * @param {string} url    - Absolute URL
+ * @param {object} [data] - JSON body
+ * @param {object} [opts] - Extra axios config (headers, timeout, …)
+ * @returns {Promise<object>} Parsed response data
+ */
+async function httpPost(url, data, opts = {}) {
+  const { headers: extraHeaders, ...rest } = opts;
+  const res = await axios({
+    method: "post",
+    url,
+    headers: baseHeaders({
+      "Content-Type": "application/json",
+      ...extraHeaders,
+    }),
+    data,
+    timeout: opts.timeout || 30000,
+    ...rest,
+  });
+  return res.data;
+}
+
+/**
+ * GET `url` and return the parsed response body.
+ *
+ * @param {string} url    - Absolute URL
+ * @param {object} [opts] - Extra axios config
+ * @returns {Promise<object>} Parsed response data
+ */
+async function httpGet(url, opts = {}) {
+  const { headers: extraHeaders, ...rest } = opts;
+  const res = await axios({
+    method: "get",
+    url,
+    headers: baseHeaders(extraHeaders),
+    timeout: opts.timeout || 30000,
+    ...rest,
+  });
+  return res.data;
+}
+
+/**
+ * PUT data to `url` (e.g. S3 presigned upload).
+ *
+ * @param {string} url    - Absolute URL
+ * @param {Buffer|string} data - Request body
+ * @param {object} [opts] - Extra axios config (headers, timeout, …)
+ * @returns {Promise<object>} Parsed response data (or empty object for 2xx with no body)
+ */
+async function httpPut(url, data, opts = {}) {
+  const { headers: extraHeaders, ...rest } = opts;
+  const res = await axios({
+    method: "put",
+    url,
+    headers: baseHeaders(extraHeaders),
+    data,
+    timeout: opts.timeout || 30000,
+    maxBodyLength: Infinity,
+    maxContentLength: Infinity,
+    ...rest,
+  });
+  return res.data;
+}
+
+/**
+ * Download a URL as a Buffer (e.g. screenshot from S3).
+ *
+ * @param {string} url    - Absolute URL
+ * @param {object} [opts] - Extra axios config
+ * @returns {Promise<Buffer>}
+ */
+async function downloadBuffer(url, opts = {}) {
+  const { headers: extraHeaders, ...rest } = opts;
+  const res = await axios({
+    method: "get",
+    url,
+    headers: baseHeaders(extraHeaders),
+    responseType: "arraybuffer",
+    timeout: opts.timeout || 60000,
+    ...rest,
+  });
+  return Buffer.from(res.data);
+}
+
+module.exports = {
+  httpPost,
+  httpGet,
+  httpPut,
+  downloadBuffer,
+  getSentryTraceHeaders,
+  USER_AGENT,
+  baseHeaders,
+};

package/agent/lib/logger.js

@@ -0,0 +1,56 @@
+/**
+ * Logger utility for TestDriver
+ * 
+ * By default, outputs to stdout (console.log).
+ * When TD_STDIO=stderr is set, outputs to stderr (console.error).
+ * This is necessary for MCP servers which use stdout exclusively for JSON-RPC.
+ */
+
+const useStderr = process.env.TD_STDIO === 'stderr';
+
+/**
+ * Log a message - uses stdout by default, stderr if TD_STDIO=stderr
+ * @param {...any} args - Arguments to log
+ */
+function log(...args) {
+  if (useStderr) {
+    console.error(...args);
+  } else {
+    console.log(...args);
+  }
+}
+
+/**
+ * Log an error - always uses stderr
+ * @param {...any} args - Arguments to log
+ */
+function error(...args) {
+  console.error(...args);
+}
+
+/**
+ * Log a warning - uses stdout by default, stderr if TD_STDIO=stderr
+ * @param {...any} args - Arguments to log
+ */
+function warn(...args) {
+  if (useStderr) {
+    console.error(...args);
+  } else {
+    console.warn(...args);
+  }
+}
+
+/**
+ * Check if logger is configured to use stderr
+ * @returns {boolean}
+ */
+function isStderrMode() {
+  return useStderr;
+}
+
+module.exports = {
+  log,
+  error,
+  warn,
+  isStderrMode,
+};

package/agent/lib/outputs.js

@@ -0,0 +1,29 @@
+// Factory function to create outputs instance
+function createOutputs() {
+  let outputs = {};
+
+  return {
+    getAll: () => {
+      return outputs;
+    },
+    get: (key) => {
+      return outputs[key] || null;
+    },
+    set: (key, value) => {
+      if (key && value) {
+        outputs[key] = value;
+      }
+    },
+  };
+}
+
+// Export both factory function and legacy static instance for backward compatibility
+const staticOutputs = createOutputs();
+
+module.exports = {
+  createOutputs,
+  // Legacy static exports for backward compatibility
+  getAll: staticOutputs.getAll,
+  get: staticOutputs.get,
+  set: staticOutputs.set,
+};

package/agent/lib/parser.js

@@ -0,0 +1,209 @@
+// parses markdown content to find code blocks, and then extracts yaml from those code blocks
+const Parser = require("markdown-parser");
+const yaml = require("js-yaml");
+const Ajv = require("ajv/dist/2020");
+const theme = require("./theme");
+const { events } = require("../events.js");
+
+let parser = new Parser();
+
+function formatAjvError(error) {
+  return [
+    theme.red("Validation Failure"),
+    `${theme.yellow("Path:")}      ${theme.white(error.instancePath)}`,
+    `${theme.yellow("Schema:")}    ${theme.cyan(error.schemaPath)}`,
+    `${theme.yellow("Keyword:")}   ${theme.magenta(error.keyword)}`,
+    error.params?.missingProperty
+      ? `${theme.yellow("Missing:")}   ${theme.yellow(
+          error.params.missingProperty,
+        )}`
+      : "",
+    `${theme.yellow("Message:")}   ${theme.white(error.message)}`,
+    `\n`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+// use markdown parser to find code blocks within AI response
+const findCodeBlocks = async function (markdownContent) {
+  let md = markdownContent.match(/```yaml\n([\s\S]*?)```/);
+
+  if (md) {
+    return [{ code: md[1] }];
+  } else {
+    return [];
+  }
+};
+
+// use markdown parser to find code blocks within AI response
+const findGenerativePrompts = async function (markdownContent) {
+  return new Promise((resolve, reject) => {
+    parser.parse(markdownContent, async (err, result) => {
+      if (err) {
+        return reject(err);
+      }
+
+      // parse the markdown content of each code block
+      let codes = result.codes.map((code) => {
+        return new Promise((resolve2, reject2) => {
+          try {
+            const yamlContent = getYAMLFromCodeBlock(code);
+            const parsedYaml = parseYAML(yamlContent);
+            resolve2(parsedYaml);
+          } catch (err) {
+            reject2(err);
+          }
+        });
+      });
+
+      // use Promise.all to wait for all the promises to resolve
+      let parsedCodes = await Promise.all(codes);
+
+      return resolve(parsedCodes);
+    });
+  });
+};
+
+// parse the yml from the included codeblock and clean it up
+const getYAMLFromCodeBlock = function (codeblock) {
+  let lines = codeblock.code.split("\n");
+
+  // if first line is yaml or yml, remove it
+  if (lines[0].indexOf("yaml") > -1 || lines[0].indexOf("yml") > -1) {
+    lines.shift();
+  }
+
+  // count the whitespace in each line, and remove the line if it's all whitespace
+  lines = lines.filter((line) => {
+    return line.trim().length > 0 && line.trim()[0] !== ",";
+    // sometimes it produces yaml with breaks, or just a single comma
+  });
+
+  return lines.join("\n");
+};
+
+// do the actual parsing
+// this library is very strict
+// note that errors are sent to the AI will it may self-heal
+const parseYAML = async function (inputYaml) {
+  let doc = await yaml.load(inputYaml);
+  return doc;
+};
+
+// Replace ${VAR} with the value from the vars object
+// Will skip variables that are not in the vars object
+// Will skip escaped variables like \${VAR}
+function interpolate(yaml, vars) {
+  let newyaml = yaml;
+  Object.keys(vars).forEach((key) => {
+    newyaml = newyaml.replace(
+      new RegExp(`(?<!\\\\)\\$\\{${key}\\}`, "g"),
+      vars[key],
+    );
+  });
+  // Replace \$ with $
+  newyaml = newyaml.replace(/\\(\${[^}]+})/g, "$1");
+
+  return newyaml;
+}
+
+// Function to gather all variables in the YAMl that have not been replaced
+function collectUnreplacedVariables(yaml) {
+  let unreplaced = [];
+
+  // Use a regex to find all ${VAR} patterns
+  const regex = /\$\{([^}]+)\}/g;
+  let match;
+  while ((match = regex.exec(yaml)) !== null) {
+    const variable = match[1];
+    // Check if the variable is already in the unreplaced array
+    if (!unreplaced.includes(variable)) {
+      unreplaced.push(variable);
+    }
+  }
+
+  return unreplaced;
+}
+
+// Factory function to create parser with emitter
+function createParser(emitter) {
+  // validate yaml using schema.json in root
+  let schema = require("../../schema.json");
+  const validateYAML = async function (yaml) {
+    let ajv = new Ajv({
+      allowUnionTypes: true,
+      strict: false,
+    });
+    let validate = ajv.compile(schema);
+    let valid = validate(await parseYAML(yaml));
+
+    if (!valid) {
+      validate.errors.forEach((err) => {
+        const formattedError = formatAjvError(err);
+        emitter.emit(events.error.fatal, formattedError);
+      });
+      // throw new Error("Invalid YAML");
+    }
+
+    return yaml;
+  };
+
+  return {
+    findCodeBlocks,
+    findGenerativePrompts,
+    getYAMLFromCodeBlock,
+    interpolate,
+    collectUnreplacedVariables,
+    validateYAML,
+    getCommands: async function (codeBlock) {
+      const yml = getYAMLFromCodeBlock(codeBlock);
+      let yamlArray = await parseYAML(yml);
+
+      let steps = yamlArray?.steps;
+
+      if (steps) {
+        let commands = [];
+
+        // combine them all as if they were a single step
+        steps.forEach((s) => {
+          commands = commands.concat(s.commands);
+        });
+
+        // filter undefined values
+        commands = commands.filter((r) => {
+          return r;
+        });
+
+        if (!commands.length) {
+          throw new Error(
+            "No actions found in yaml. Individual commands must be under the `commands` key.",
+          );
+        }
+
+        return commands;
+      } else {
+        let commands = yamlArray?.commands;
+
+        if (!commands?.length) {
+          throw new Error(
+            "No actions found in yaml. Individual commands must be under the `commands` key.",
+          );
+        }
+
+        return commands;
+      }
+    },
+  };
+}
+
+// Export both the factory function and the static functions for backward compatibility
+module.exports = {
+  createParser,
+  // Static exports for backward compatibility
+  findCodeBlocks,
+  findGenerativePrompts,
+  getYAMLFromCodeBlock,
+  interpolate,
+  collectUnreplacedVariables,
+};