@diegosouzacdv/jev-browser-mcp 0.7.1 → 0.7.2

package/mcp_servers/jev-browser-npm/src/test-suites.mjs

@@ -0,0 +1,438 @@
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import packageManifest from "../../../package.json" with { type: "json" };
+import { JevBrowserError } from "./config.mjs";
+import { createIntegrationSession } from "./test-integrations.mjs";
+import { validateBrowserFlowRequest } from "./flow.mjs";
+
+const SUITE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$/;
+const suiteDirectoryName = ".jev-browser/suites";
+const reportDirectoryName = ".jev-browser/reports";
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactFields(value, required, optional, label) {
+  if (!isRecord(value)) throw new JevBrowserError(`${label} must be an object`);
+  const allowed = new Set([...required, ...optional]);
+  const missing = required.filter((key) => !Object.hasOwn(value, key));
+  const unsupported = Object.keys(value).filter((key) => !allowed.has(key));
+  if (missing.length || unsupported.length) {
+    throw new JevBrowserError(`${label} has invalid fields${missing.length ? `; missing: ${missing.join(", ")}` : ""}${unsupported.length ? `; unsupported: ${unsupported.join(", ")}` : ""}`);
+  }
+}
+
+function validateFlowDefinition(definition, label) {
+  exactFields(definition, ["flow", "candidate_plans"], ["initial_url", "expected_outcome", "params", "options"], label);
+}
+
+function safeProjectPath(projectRoot, relativePath) {
+  if (typeof relativePath !== "string" || !relativePath.trim() || path.isAbsolute(relativePath) || path.win32.isAbsolute(relativePath)
+    || relativePath.split(/[\\/]+/).includes("..")) throw new JevBrowserError("suite/report path must be relative and stay inside the project");
+  const root = path.resolve(projectRoot);
+  const target = path.resolve(root, relativePath);
+  const relative = path.relative(root, target);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new JevBrowserError("suite/report path must stay inside the project");
+  }
+  return target;
+}
+
+async function ensureSafeParent(projectRoot, target) {
+  const root = await realpath(projectRoot);
+  let current = root;
+  for (const part of path.relative(root, path.dirname(target)).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink() || !info.isDirectory()) throw new JevBrowserError("suite/report directory must not contain symlinks");
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      await mkdir(current, { mode: 0o700 });
+    }
+    const resolved = await realpath(current);
+    const relative = path.relative(root, resolved);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new JevBrowserError("suite/report directory resolves outside the project");
+    }
+    current = resolved;
+  }
+}
+
+async function preflightReportTarget(projectRoot, target) {
+  const root = await realpath(projectRoot);
+  let current = root;
+  const parentParts = path.relative(root, path.dirname(target)).split(path.sep).filter(Boolean);
+  for (const part of parentParts) {
+    current = path.join(current, part);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink() || !info.isDirectory()) throw new JevBrowserError("suite/report directory must not contain symlinks or non-directories");
+      current = await realpath(current);
+    } catch (error) {
+      if (error?.code === "ENOENT") break;
+      throw error;
+    }
+  }
+  try {
+    const info = await lstat(target);
+    if (info.isSymbolicLink() || !info.isFile()) throw new JevBrowserError("report destination must be a regular non-symlink file");
+    throw new JevBrowserError("report destination already exists");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+function validateSuiteDocument(document, suiteName, settings) {
+  exactFields(document, ["version", "id", "criteria"], ["description", "environment_profile", "params", "flows", "setup", "teardown"], "test suite");
+  if (document.version !== 1) throw new JevBrowserError("test suite version must be 1");
+  if (document.id !== suiteName) throw new JevBrowserError("test suite id must match suite_name");
+  if (document.description !== undefined && (typeof document.description !== "string" || document.description.length > 2000)) throw new JevBrowserError("test suite description must be at most 2000 characters");
+  if (document.environment_profile !== undefined && (typeof document.environment_profile !== "string" || !document.environment_profile.trim())) throw new JevBrowserError("test suite environment_profile must be a non-empty profile name");
+  if (document.params !== undefined && !isRecord(document.params)) throw new JevBrowserError("test suite params must be an object");
+  if (document.flows !== undefined && !isRecord(document.flows)) throw new JevBrowserError("test suite flows must be an object of reusable flow definitions");
+  for (const key of ["setup", "teardown"]) {
+    if (document[key] !== undefined && typeof document[key] !== "string" && !isRecord(document[key])) throw new JevBrowserError(`test suite ${key} must reference a reusable flow or define one inline`);
+  }
+  if (!Array.isArray(document.criteria) || !document.criteria.length || document.criteria.length > settings.browser.maxTestSuiteCriteria) throw new JevBrowserError("test suite criteria count exceeds the configured suite limit");
+  for (const [name, definition] of Object.entries(document.flows || {})) {
+    if (!SUITE_NAME.test(name)) throw new JevBrowserError(`invalid reusable flow name ${name}`);
+    validateFlowDefinition(definition, `flows.${name}`);
+  }
+  const ids = new Set();
+  for (const [index, criterion] of document.criteria.entries()) {
+    exactFields(criterion, ["id", "description", "flow"], ["initial_url", "expected_outcome", "params", "options"], `criteria[${index}]`);
+    if (typeof criterion.id !== "string" || !SUITE_NAME.test(criterion.id) || ids.has(criterion.id)) throw new JevBrowserError(`criteria[${index}].id must be unique and valid`);
+    ids.add(criterion.id);
+    if (typeof criterion.description !== "string" || !criterion.description.trim() || criterion.description.length > 2000) throw new JevBrowserError(`criteria[${index}].description is required and limited to 2000 characters`);
+    if (typeof criterion.flow !== "string" && !isRecord(criterion.flow)) throw new JevBrowserError(`criteria[${index}].flow must reference a reusable flow or define one inline`);
+    if (isRecord(criterion.flow)) validateFlowDefinition(criterion.flow, `criteria[${index}].flow`);
+  }
+}
+
+async function readTestSuite(settings, suiteName) {
+  if (typeof suiteName !== "string" || !SUITE_NAME.test(suiteName)) throw new JevBrowserError("suite_name must use letters, numbers, hyphen, or underscore");
+  const filePath = safeProjectPath(settings.browser.projectRoot, path.join(suiteDirectoryName, `${suiteName}.json`));
+  try {
+    const info = await lstat(filePath);
+    if (info.isSymbolicLink() || !info.isFile() || info.size > settings.browser.maxTestSuiteFileBytes) throw new JevBrowserError("suite file must be a regular non-symlink JSON file within the configured size limit");
+    if (await realpath(filePath) !== path.resolve(filePath)) throw new JevBrowserError("suite file must not use symlinks");
+    const document = JSON.parse(await readFile(filePath, "utf8"));
+    validateSuiteDocument(document, suiteName, settings);
+    return document;
+  } catch (error) {
+    if (error instanceof JevBrowserError) throw error;
+    if (error?.code === "ENOENT") throw new JevBrowserError(`test suite ${suiteName} was not found at ${path.join(suiteDirectoryName, `${suiteName}.json`)}`);
+    throw new JevBrowserError("test suite file is unreadable or invalid JSON");
+  }
+}
+
+function resolveFlowDefinition(document, source, defaults, overrides = {}) {
+  const base = typeof source === "string" ? document.flows?.[source] : source;
+  if (!base) throw new JevBrowserError(`unknown reusable flow ${JSON.stringify(source)}`);
+  const combined = { ...base, ...overrides };
+  const mergedParams = { ...(document.params || {}), ...(base.params || {}), ...(overrides.params || {}) };
+  const profile = overrides.options?.environment_profile || base.options?.environment_profile || defaults.environmentProfile;
+  const options = { ...(base.options || {}), ...(overrides.options || {}) };
+  if (profile && !options.environment_profile) options.environment_profile = profile;
+  return {
+    flow: combined.flow,
+    initialUrl: combined.initial_url,
+    expectedOutcome: combined.expected_outcome,
+    candidatePlans: combined.candidate_plans,
+    params: mergedParams,
+    options,
+    settings: defaults.settings,
+    browserPool: defaults.browserPool,
+    fetchImpl: defaults.fetchImpl,
+    serverVersion: defaults.serverVersion,
+    mutationAuthorizationStore: defaults.mutationAuthorizationStore,
+    integrationSession: defaults.integrationSession,
+    retainUploadStaging: true,
+  };
+}
+
+function referencedDefinition(document, reference) {
+  if (typeof reference === "string") return document.flows?.[reference];
+  return reference;
+}
+
+function collectReportSecrets(settings, suite, params) {
+  const references = new Set([settings.jev.credentialEnv]);
+  const add = (value) => { if (typeof value === "string" && value.length >= 4) references.add(value); };
+  const profiles = settings.browser.environmentProfiles.profiles;
+  for (const profile of Object.values(profiles)) {
+    add(profile.database?.connectionEnv);
+    add(profile.database?.connectEnv);
+    add(profile.database?.userEnv);
+    add(profile.database?.passwordEnv);
+    for (const remote of Object.values(profile.remotes)) {
+      add(remote.usernameEnv);
+      add(remote.passwordEnv);
+      add(remote.hostFingerprintEnv);
+    }
+  }
+  const secrets = new Set([...references].map((name) => settings.env[name]).filter((value) => typeof value === "string" && value.length >= 4));
+  const inspect = (value, sensitiveParent = false) => {
+    if (typeof value === "string") {
+      if (sensitiveParent && value.length >= 4) secrets.add(value);
+      return;
+    }
+    if (Array.isArray(value)) { for (const item of value) inspect(item, sensitiveParent); return; }
+    if (!isRecord(value)) return;
+    if (value.action === "type" && value.sensitive !== false) addSensitiveText(value.text);
+    if (typeof value.text_env === "string") {
+      const textSecret = settings.env[value.text_env];
+      if (typeof textSecret === "string" && textSecret.length >= 4) secrets.add(textSecret);
+    }
+    for (const [key, item] of Object.entries(value)) {
+      inspect(item, sensitiveParent || /pass(?:word)?|secret|token|authorization|cookie|credential|api[_-]?key|private[_-]?key/i.test(key));
+    }
+  };
+  const addSensitiveText = (value) => { if (typeof value === "string" && value.length >= 4) secrets.add(value); };
+  inspect(suite);
+  inspect(params);
+  return [...secrets].sort((left, right) => right.length - left.length);
+}
+
+function redactReportText(value, secrets) {
+  let result = String(value);
+  for (const secret of secrets) if (secret) result = result.replaceAll(secret, "[redacted]");
+  return result;
+}
+
+function boundedReport(text, maxBytes) {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.length <= maxBytes) return { text, truncated: false };
+  const marker = "\n\n[Report truncated at the configured byte limit.]\n";
+  const available = Math.max(0, maxBytes - Buffer.byteLength(marker));
+  const prefix = bytes.subarray(0, available).toString("utf8").replace(/\uFFFD$/, "");
+  return { text: `${prefix}${marker}`, truncated: true };
+}
+
+function reportNetworkUrl(value, secrets = []) {
+  try {
+    const url = new URL(value);
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    url.pathname = url.pathname.split("/").map((part) => /^\d{4,}$/.test(part) || /^[0-9a-f]{8}-[0-9a-f-]{27,}$/i.test(part) || /^[A-Za-z0-9_-]{32,}$/.test(part) ? "[redacted]" : part).join("/");
+    return redactReportText(url.toString(), secrets);
+  } catch {
+    return "[redacted]";
+  }
+}
+
+function renderReport(suite, results, cleanup, startedAt, finishedAt, secrets) {
+  const lines = [
+    `# Jev Browser test suite: ${suite.id}`,
+    "",
+    redactReportText(suite.description || "Automated suite report.", secrets),
+    "",
+    `- Server: ${packageManifest.version}`,
+    `- Started: ${startedAt}`,
+    `- Finished: ${finishedAt}`,
+    `- Result: ${results.every((item) => item.status === "passed") && cleanup.status === "passed" ? "PASSED" : "FAILED"}`,
+    "",
+    "## Acceptance criteria",
+    "",
+  ];
+  for (const item of results) {
+    lines.push(`### ${item.id}: ${item.status.toUpperCase()}`, "", redactReportText(item.description, secrets), "");
+    if (item.reason) lines.push(`Failure: ${redactReportText(item.reason.replace(/\s+/g, " ").slice(0, 1000), secrets)}`, "");
+    for (const step of item.steps || []) {
+      const details = [
+        step.action && `action=${step.action}`,
+        step.duration_ms !== undefined && `duration_ms=${step.duration_ms}`,
+        step.status && `status=${step.status}`,
+        step.method && `method=${step.method}`,
+        step.url && `url=${reportNetworkUrl(step.url, secrets)}`,
+        step.response_status !== undefined && `http=${step.response_status}`,
+        step.engine && `database=${step.engine}`,
+        step.row_count !== undefined && `rows=${step.row_count}`,
+        step.scanned_bytes !== undefined && `scanned_bytes=${step.scanned_bytes}`,
+        step.truncated !== undefined && `truncated=${step.truncated}`,
+        step.sha256_matched !== undefined && `sha256_matched=${step.sha256_matched}`,
+        step.sha256 && `sha256=${step.sha256}`,
+        step.size_bytes !== undefined && `size_bytes=${step.size_bytes}`,
+        step.mime_type && `mime=${step.mime_type}`,
+        step.source && `source=${step.source}`,
+        step.server && `server=${step.server}`,
+        step.exists !== undefined && `exists=${step.exists}`,
+        step.recipient_matched !== undefined && `recipient_matched=${step.recipient_matched}`,
+        step.subject_matched !== undefined && `subject_matched=${step.subject_matched}`,
+        step.body_matched !== undefined && `body_matched=${step.body_matched}`,
+        step.received_at && `received_at=${step.received_at}`,
+        step.hook && `hook=${step.hook}`,
+        step.asserted !== undefined && `asserted=${step.asserted}`,
+        step.screenshot_path && `screenshot=${redactReportText(step.screenshot_path, secrets)}`,
+      ].filter(Boolean).join(", ");
+      lines.push(`- Step ${step.step || "?"}: ${details || "completed"}`);
+    }
+    for (const itemNetwork of item.network_events || []) {
+      lines.push(`- Network: ${itemNetwork.method || "?"} ${reportNetworkUrl(itemNetwork.url || "", secrets)} → ${itemNetwork.status ?? "failed"}`);
+    }
+    if (!(item.steps || []).length) lines.push("- No browser steps executed.");
+    lines.push("");
+  }
+  lines.push("## Cleanup", "", `- ${cleanup.status}${cleanup.files_removed ? "; project-local temporary files removed" : ""}${cleanup.reason ? `: ${redactReportText(cleanup.reason, secrets)}` : ""}`, "");
+  return `${lines.join("\n")}\n`;
+}
+
+function criterionEvidence(definition, result) {
+  const steps = result?.steps || result?.trace || [];
+  return {
+    id: definition.id,
+    description: definition.description,
+    status: result?.status === "passed" ? "passed" : result?.status === "skipped" ? "skipped" : "failed",
+    reason: result?.reason,
+    steps,
+    network_events: result?.network_events || result?.network_failures || [],
+    screenshots: steps.map((step) => step.screenshot_path).filter(Boolean),
+    result,
+  };
+}
+
+export async function executeTestSuite({ suiteName, params, environmentProfile, reportPath, settings, browserPool, executeFlow, fetchImpl, serverVersion, mutationAuthorizationStore }) {
+  const suite = await readTestSuite(settings, suiteName);
+  const destination = reportPath || path.join(reportDirectoryName, `${suite.id}-${Date.now()}.md`);
+  const reportTarget = safeProjectPath(settings.browser.projectRoot, destination);
+  await preflightReportTarget(settings.browser.projectRoot, reportTarget);
+  const definitions = [];
+  const defaults = { settings, browserPool, fetchImpl, serverVersion, mutationAuthorizationStore, environmentProfile: environmentProfile || suite.environment_profile };
+  const addDefinition = (id, description, source, overrides) => {
+    const resolved = resolveFlowDefinition(suite, source, defaults, { ...overrides, params: { ...(suite.params || {}), ...(params || {}), ...(overrides?.params || {}) } });
+    validateBrowserFlowRequest(resolved);
+    definitions.push({ id, description, resolved });
+  };
+  let setupDefinition;
+  let teardownDefinition;
+  if (suite.setup !== undefined) {
+    const source = referencedDefinition(suite, suite.setup);
+    if (!source) throw new JevBrowserError(`unknown setup flow ${JSON.stringify(suite.setup)}`);
+    if (typeof suite.setup !== "string") validateFlowDefinition(source, "setup");
+    setupDefinition = resolveFlowDefinition(suite, source, defaults, { params: { ...(suite.params || {}), ...(params || {}) } });
+    validateBrowserFlowRequest(setupDefinition);
+  }
+  for (const criterion of suite.criteria) {
+    const source = criterion.flow;
+    const criterionOverrides = Object.fromEntries(["initial_url", "expected_outcome", "params", "options"].filter((key) => Object.hasOwn(criterion, key)).map((key) => [key, criterion[key]]));
+    const overrides = typeof criterion.flow === "string"
+      ? criterionOverrides
+      : { ...criterion.flow, ...criterionOverrides };
+    addDefinition(criterion.id, criterion.description, source, overrides);
+  }
+  if (suite.teardown !== undefined) {
+    const source = referencedDefinition(suite, suite.teardown);
+    if (!source) throw new JevBrowserError(`unknown teardown flow ${JSON.stringify(suite.teardown)}`);
+    if (typeof suite.teardown !== "string") validateFlowDefinition(source, "teardown");
+    teardownDefinition = resolveFlowDefinition(suite, source, defaults, { params: { ...(suite.params || {}), ...(params || {}) } });
+    validateBrowserFlowRequest(teardownDefinition);
+  }
+
+  const profileIds = new Set([
+    environmentProfile,
+    suite.environment_profile,
+    setupDefinition?.options.environment_profile,
+    ...definitions.map((item) => item.resolved.options.environment_profile),
+    teardownDefinition?.options.environment_profile,
+  ].filter(Boolean));
+  if (profileIds.size > 1) throw new JevBrowserError("one test suite must use a single environment profile");
+  const profileId = [...profileIds][0];
+  const session = createIntegrationSession(settings, profileId);
+  const reportSecrets = collectReportSecrets(settings, suite, params);
+  const startedAt = new Date().toISOString();
+  const results = [];
+  let suiteFailed = false;
+  let setupPassed = !setupDefinition;
+  let cleanup = { status: "not_required" };
+  let reportError;
+  let reportTruncated = false;
+  try {
+    await session.markFlowStart();
+    if (setupDefinition) {
+      const result = await executeFlow({ ...setupDefinition, integrationSession: session, retainUploadStaging: true });
+      setupPassed = result.status === "passed";
+      if (!setupPassed) suiteFailed = true;
+      results.push({ id: "setup", description: "Suite setup", ...criterionEvidence({ id: "setup", description: "Suite setup" }, result) });
+    }
+    for (const item of definitions) {
+      if (!setupPassed) {
+        results.push({ id: item.id, description: item.description, status: "skipped", reason: "setup did not pass", steps: [] });
+        suiteFailed = true;
+        continue;
+      }
+      try {
+        const result = await executeFlow({ ...item.resolved, integrationSession: session, retainUploadStaging: true });
+        const evidence = criterionEvidence(item, result);
+        results.push(evidence);
+        if (evidence.status !== "passed") suiteFailed = true;
+      } catch (error) {
+        results.push({ id: item.id, description: item.description, status: "failed", reason: error?.message || "criterion flow failed", steps: [] });
+        suiteFailed = true;
+      }
+    }
+  } catch (error) {
+    suiteFailed = true;
+    results.push({ id: "setup", description: "Suite setup", status: "failed", reason: error?.message || "suite setup failed", steps: [] });
+  } finally {
+    if (teardownDefinition) {
+      try {
+        const result = await executeFlow({ ...teardownDefinition, integrationSession: session, retainUploadStaging: true });
+        const teardown = criterionEvidence({ id: "teardown", description: "Suite teardown" }, result);
+        results.push(teardown);
+        cleanup = { status: result.status === "passed" ? "passed" : "failed", ...(result.reason ? { reason: result.reason } : {}) };
+        if (cleanup.status !== "passed") suiteFailed = true;
+      } catch (error) {
+        cleanup = { status: "failed", reason: error?.message || "suite teardown failed" };
+        results.push({ id: "teardown", description: "Suite teardown", status: "failed", reason: cleanup.reason, steps: [] });
+        suiteFailed = true;
+      }
+    }
+    await session.close();
+    try {
+      if (settings.browser.managedUploadStaging) {
+        const { cleanupUploadStagingDirectory } = await import("./upload-staging.mjs");
+        await cleanupUploadStagingDirectory(settings);
+        cleanup.status = cleanup.status === "failed" ? cleanup.status : "passed";
+        cleanup.files_removed = true;
+      }
+    } catch {
+      cleanup.status = "failed";
+      cleanup.reason = "temporary fixture cleanup failed";
+      suiteFailed = true;
+    }
+  }
+
+  const finishedAt = new Date().toISOString();
+  try {
+    await ensureSafeParent(settings.browser.projectRoot, reportTarget);
+    try {
+      const existing = await lstat(reportTarget);
+      if (existing.isSymbolicLink() || !existing.isFile()) throw new JevBrowserError("report destination must be a regular non-symlink file");
+    } catch (error) { if (error?.code !== "ENOENT") throw error; }
+    const report = boundedReport(renderReport(suite, results, cleanup, startedAt, finishedAt, reportSecrets), settings.browser.maxTestSuiteReportBytes);
+    await writeFile(reportTarget, report.text, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    reportTruncated = report.truncated;
+  } catch (error) {
+    reportError = error instanceof Error ? error.message : "report could not be saved";
+    suiteFailed = true;
+  }
+  return {
+    status: suiteFailed ? "failed" : "passed",
+    suite_id: suite.id,
+    server_version: serverVersion || packageManifest.version,
+    environment_profile: profileId,
+    started_at: startedAt,
+    finished_at: finishedAt,
+    acceptance_criteria: results.map(({ result: _result, ...item }) => item),
+    cleanup,
+    ...(reportTarget && !reportError ? { report_path: reportTarget } : {}),
+    ...(reportTruncated ? { report_truncated: true } : {}),
+    ...(reportError ? { report_error: reportError } : {}),
+  };
+}
+
+export const testSuiteLocation = (name) => path.join(suiteDirectoryName, `${name}.json`);

package/mcp_servers/jev-browser-npm/src/upload-staging.mjs

@@ -0,0 +1,80 @@
+import { lstat, mkdir, readdir, realpath, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { JevBrowserError } from "./config.mjs";
+
+const stagingQueues = new Map();
+
+function isWithin(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+async function checkedStagingDirectory(settings, { create, missingIsAllowed = false }) {
+  const projectRoot = path.resolve(settings.browser.projectRoot);
+  const stagingDirectory = path.resolve(settings.browser.uploadStagingDirectory);
+  if (!settings.browser.managedUploadStaging || !isWithin(projectRoot, stagingDirectory)) {
+    throw new JevBrowserError("managed upload staging directory must stay inside the configured project");
+  }
+  try {
+    const projectInfo = await stat(projectRoot);
+    if (!projectInfo.isDirectory()) throw new Error("project root is not a directory");
+    const realProjectRoot = await realpath(projectRoot);
+    let current = realProjectRoot;
+    const relative = path.relative(projectRoot, stagingDirectory);
+    for (const part of relative.split(path.sep)) {
+      current = path.join(current, part);
+      try {
+        const info = await lstat(current);
+        if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("staging path is not a real directory");
+      } catch (error) {
+        if (error?.code !== "ENOENT") throw error;
+        if (!create) {
+          if (missingIsAllowed) return undefined;
+          throw error;
+        }
+        try {
+          await mkdir(current, { mode: 0o700 });
+        } catch (createError) {
+          if (createError?.code !== "EEXIST") throw createError;
+        }
+      }
+      const resolved = await realpath(current);
+      if (!isWithin(realProjectRoot, resolved)) throw new Error("staging path resolves outside the project");
+      current = resolved;
+    }
+    return current;
+  } catch (error) {
+    if (missingIsAllowed && error?.code === "ENOENT") return undefined;
+    throw new JevBrowserError("managed upload staging directory is unavailable or resolves outside the project");
+  }
+}
+
+export async function prepareUploadStagingDirectory(settings) {
+  if (!settings.browser.managedUploadStaging) return undefined;
+  return checkedStagingDirectory(settings, { create: true });
+}
+
+export async function cleanupUploadStagingDirectory(settings) {
+  if (!settings.browser.managedUploadStaging) return false;
+  const stagingDirectory = await checkedStagingDirectory(settings, { create: false, missingIsAllowed: true });
+  if (!stagingDirectory) return false;
+  const entries = await readdir(stagingDirectory);
+  await Promise.all(entries.map((entry) => rm(path.join(stagingDirectory, entry), { recursive: true, force: true })));
+  return true;
+}
+
+export async function withUploadStagingLock(settings, operation) {
+  if (!settings.browser.managedUploadStaging) return operation();
+  const key = path.resolve(settings.browser.uploadStagingDirectory);
+  const previous = stagingQueues.get(key) || Promise.resolve();
+  let release;
+  const current = new Promise((resolve) => { release = resolve; });
+  stagingQueues.set(key, current);
+  await previous;
+  try {
+    return await operation();
+  } finally {
+    release();
+    if (stagingQueues.get(key) === current) stagingQueues.delete(key);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegosouzacdv/jev-browser-mcp",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Portable MCP server for bounded Playwright screen flows selected by Jev",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,13 @@
   "dependencies": {
     "@axe-core/playwright": "4.13.0",
     "@modelcontextprotocol/server": "2.1.0",
+    "basic-ftp": "6.2.1",
+    "mailparser": "3.9.33",
+    "oracledb": "7.0.1",
+    "pg": "8.23.1",
     "playwright": "1.63.0",
+    "smtp-server": "3.19.16",
+    "ssh2-sftp-client": "12.1.1",
     "zod": "4.6.5"
   }
 }