@drip-apex/sdk 0.1.0

package/src/editor/command-runtime.ts

@@ -0,0 +1,572 @@
+import type { Mutation, MutationAction } from "../types";
+import { EditorApi, EditorApiError } from "./api";
+import type { ArtifactCommandAudit, EditorController } from "./controller";
+import { generateDeterministicSelector } from "./selector";
+import type {
+  ClaimedEditorCommand,
+  EditorArtifacts,
+  EditorBrowserCommand,
+} from "./types";
+
+const POLL_INTERVAL_MS = 900;
+const MAX_LOGS = 80;
+const REDACTED = "[redacted]";
+const SENSITIVE_KEY = /(?:account|address|auth(?:orization)?|bearer|card|cookie|credential|customer|cvv|email|name|pass(?:word|wd)?|payment|phone|postal|secret|session|ssn|token|user|value|zip)/i;
+const EMAIL = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const JWT = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g;
+const AUTH_VALUE = /\b(?:bearer|basic)\s+[A-Za-z0-9._~+\/-]+=*/gi;
+const LONG_NUMBER = /\b(?:\+?\d[\d .()-]{6,}\d)\b/g;
+const MUTATION_ACTIONS = new Set<MutationAction>([
+  "html", "text", "setText", "attribute", "style", "setStyle", "remove",
+  "insertBefore", "insertAfter",
+]);
+
+export type EditorCommandResult = { ok: boolean; [key: string]: unknown };
+type CommandExecution = {
+  result: EditorCommandResult;
+  afterAcknowledge?: () => void;
+};
+
+type NavigationActions = {
+  navigate(url: string): void;
+  reload(): void;
+  back(): void;
+  forward(): void;
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function string(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function isLoopbackOrigin(origin: string): boolean {
+  try {
+    const hostname = new URL(origin).hostname.toLowerCase();
+    return hostname === "localhost" || hostname.endsWith(".localhost") ||
+      hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+  } catch {
+    return false;
+  }
+}
+
+function sanitizedUrl(value: string, base?: string): string {
+  try {
+    const url = new URL(value, base);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return `${url.protocol}${REDACTED}`;
+    }
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return REDACTED;
+  }
+}
+
+function sanitizeDiagnosticText(value: string): string {
+  return value
+    .replace(/https?:\/\/[^\s"'<>]+/gi, (url) => sanitizedUrl(url))
+    .replace(EMAIL, REDACTED)
+    .replace(JWT, REDACTED)
+    .replace(AUTH_VALUE, REDACTED)
+    .replace(LONG_NUMBER, REDACTED)
+    .replace(/\b(?:api[-_]?key|authorization|cookie|password|secret|token)\s*[:=]\s*[^\s,;]+/gi, (match) => {
+      const separator = match.includes(":") ? ":" : "=";
+      return `${match.split(separator, 1)[0]}${separator}${REDACTED}`;
+    });
+}
+
+function cloneSafe(value: unknown, depth = 0, key = ""): unknown {
+  if (key && SENSITIVE_KEY.test(key)) return REDACTED;
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return typeof value === "string" ? sanitizeDiagnosticText(value).slice(0, 500) : value;
+  }
+  if (typeof value === "undefined") return null;
+  if (depth > 4) return "[truncated]";
+  if (value instanceof Element) return elementSummary(value);
+  if (Array.isArray(value)) return value.slice(0, 120).map((item) => cloneSafe(item, depth + 1));
+  if (typeof value === "object") {
+    const output: Record<string, unknown> = {};
+    for (const [entryKey, entry] of Object.entries(value as Record<string, unknown>).slice(0, 80)) {
+      try { output[entryKey] = cloneSafe(entry, depth + 1, entryKey); } catch {}
+    }
+    return output;
+  }
+  return `[${typeof value}]`;
+}
+
+function visibleText(element: Element | null): string {
+  if (!element) return "";
+  if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement || element instanceof HTMLFormElement ||
+    (element instanceof HTMLElement && element.isContentEditable)) {
+    return "";
+  }
+  return (element.textContent ?? "").trim().replace(/\s+/g, " ");
+}
+
+function elementSummary(element: Element | null): Record<string, unknown> | null {
+  if (!element) return null;
+  let rect: Record<string, number> | null = null;
+  try {
+    const box = element.getBoundingClientRect();
+    rect = {
+      x: Math.round(box.x), y: Math.round(box.y),
+      width: Math.round(box.width), height: Math.round(box.height),
+    };
+  } catch {}
+  return {
+    selector: generateDeterministicSelector(element),
+    tag: element.tagName.toLowerCase(),
+    text: sanitizeDiagnosticText(visibleText(element)).slice(0, 220) || null,
+    role: element.getAttribute("role"),
+    href: element instanceof HTMLAnchorElement ? sanitizedUrl(element.href) : null,
+    name: element.getAttribute("name"),
+    type: element.getAttribute("type"),
+    rect,
+  };
+}
+
+function sanitizeNetworkEntry(entry: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...cloneSafe(entry) as Record<string, unknown>,
+    ...(typeof entry.url === "string" ? { url: sanitizedUrl(entry.url) } : {}),
+  };
+}
+
+function findTarget(args: Record<string, unknown>): {
+  ok: boolean;
+  element?: Element;
+  mode?: string;
+  error?: string;
+  repairHint?: string;
+} {
+  const selector = string(args.selector);
+  if (selector) {
+    try {
+      const element = document.querySelector(selector);
+      return element
+        ? { ok: true, element, mode: "selector" }
+        : {
+            ok: false,
+            error: "Selector target not found.",
+            repairHint: "Call browser_snapshot or browser_select_element to find a selector that exists on the live page.",
+          };
+    } catch {
+      return {
+        ok: false,
+        error: `Invalid selector: ${selector}`,
+        repairHint: "Pass visible text or a valid CSS selector.",
+      };
+    }
+  }
+  const query = string(args.text ?? args.selectorOrText ?? args.instruction ?? args.condition);
+  if (!query) return { ok: false, error: "Target not found" };
+  try {
+    const element = document.querySelector(query);
+    if (element) return { ok: true, element, mode: "selectorOrText" };
+  } catch {}
+  const lower = query.toLowerCase();
+  const candidates = Array.from(document.querySelectorAll(
+    "button,a,input,textarea,select,label,[role='button'],[onclick],[data-testid]",
+  )).slice(0, 350).filter((element) => {
+    const aria = `${element.getAttribute("aria-label") ?? ""} ${element.getAttribute("title") ?? ""} ${element.getAttribute("value") ?? ""}`.toLowerCase();
+    return visibleText(element).toLowerCase().includes(lower) || aria.includes(lower);
+  });
+  if (candidates.length === 1) return { ok: true, element: candidates[0], mode: "text" };
+  if (candidates.length > 1) {
+    return {
+      ok: false,
+      error: "Browser target text is ambiguous.",
+      repairHint: "Pass the exact selector from browser_snapshot/browser_select_element instead of loose text.",
+    };
+  }
+  return { ok: false, error: "Target not found" };
+}
+
+function parseMutation(value: unknown): Mutation | null {
+  const input = record(value);
+  const selector = string(input?.selector);
+  const action = input?.action;
+  if (!selector || typeof action !== "string" || !MUTATION_ACTIONS.has(action as MutationAction)) return null;
+  const mutation: Mutation = { selector, action: action as MutationAction };
+  if (typeof input?.html === "string") mutation.html = input.html;
+  if (typeof input?.text === "string") mutation.text = input.text;
+  const attribute = record(input?.attribute);
+  if (attribute && typeof attribute.name === "string" &&
+    (typeof attribute.value === "string" || attribute.value === null)) {
+    mutation.attribute = { name: attribute.name, value: attribute.value };
+  }
+  const attributes = record(input?.attributes);
+  if (attributes) {
+    mutation.attributes = Object.fromEntries(Object.entries(attributes).filter(
+      ([, entry]) => typeof entry === "string" || entry === null,
+    )) as Record<string, string | null>;
+  }
+  const styles = record(input?.styles);
+  if (styles) {
+    mutation.styles = Object.fromEntries(Object.entries(styles).filter(
+      ([, entry]) => typeof entry === "string",
+    )) as Record<string, string>;
+  }
+  return mutation;
+}
+
+function parseArtifacts(value: unknown): EditorArtifacts | null {
+  const input = record(value);
+  if (!input || !Array.isArray(input.mutations)) return null;
+  const mutations = input.mutations.map(parseMutation);
+  if (mutations.some((mutation) => mutation === null)) return null;
+  return {
+    mutations: mutations as Mutation[],
+    customCss: typeof input.customCss === "string" ? input.customCss : "",
+    customJs: typeof input.customJs === "string" ? input.customJs : "",
+  };
+}
+
+function auditResult(audit: ArtifactCommandAudit): EditorCommandResult {
+  return { ...audit };
+}
+
+export class EditorCommandExecutor {
+  private readonly consoleLogs: Array<Record<string, unknown>> = [];
+  private readonly networkLogs: Array<Record<string, unknown>> = [];
+  private restoreConsole: (() => void) | null = null;
+  private performanceObserver: PerformanceObserver | null = null;
+
+  constructor(
+    private readonly controller: EditorController,
+    private readonly navigation: NavigationActions = {
+      navigate: (url) => location.assign(url),
+      reload: () => location.reload(),
+      back: () => history.back(),
+      forward: () => history.forward(),
+    },
+  ) {}
+
+  start(): void {
+    if (this.restoreConsole) return;
+    const originals = new Map<"log" | "info" | "warn" | "error", (...args: unknown[]) => void>();
+    for (const level of ["log", "info", "warn", "error"] as const) {
+      const original = console[level];
+      originals.set(level, original);
+      console[level] = (...args: unknown[]) => {
+        this.consoleLogs.push({ level, args: cloneSafe(args), ts: Date.now() });
+        this.consoleLogs.splice(0, Math.max(0, this.consoleLogs.length - MAX_LOGS));
+        original.apply(console, args);
+      };
+    }
+    this.restoreConsole = () => {
+      for (const [level, original] of originals) console[level] = original;
+      this.restoreConsole = null;
+    };
+    if (typeof PerformanceObserver !== "undefined") {
+      try {
+        this.performanceObserver = new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            this.networkLogs.push({
+              url: entry.name,
+              type: entry.entryType,
+              startTime: Math.round(entry.startTime),
+              duration: Math.round(entry.duration),
+            });
+          }
+          this.networkLogs.splice(0, Math.max(0, this.networkLogs.length - MAX_LOGS));
+        });
+        this.performanceObserver.observe({ type: "resource", buffered: true });
+      } catch {}
+    }
+  }
+
+  stop(): void {
+    this.restoreConsole?.();
+    this.performanceObserver?.disconnect();
+    this.performanceObserver = null;
+  }
+
+  async execute(command: ClaimedEditorCommand): Promise<CommandExecution> {
+    const args = command.args;
+    switch (command.command) {
+      case "current_url":
+        return {
+          result: {
+            ok: true,
+            url: sanitizedUrl(location.href),
+            originalUrl: sanitizedUrl(location.href),
+          },
+        };
+      case "snapshot":
+        return { result: { ok: true, snapshot: this.snapshot() } };
+      case "console_logs":
+        return {
+          result: {
+            ok: true,
+            logs: this.consoleLogs.slice(-50).map(
+              (entry) => cloneSafe(entry) as Record<string, unknown>,
+            ),
+          },
+        };
+      case "network_logs": {
+        const filter = string(args.filter).toLowerCase();
+        const logs = this.networkLogs.slice(-80).map(sanitizeNetworkEntry).filter(
+          (entry) => !filter || JSON.stringify(entry).toLowerCase().includes(filter),
+        );
+        return { result: { ok: true, logs } };
+      }
+      case "screenshot":
+        return {
+          result: {
+            ok: false,
+            error: "Live-page screenshot capture is unsupported in the merchant SDK runtime.",
+            repairHint: "Use browser_snapshot for DOM evidence or capture the store tab through the connected browser runner.",
+            screenshot: { captured: false, reason: "unsupported_live_origin" },
+          },
+        };
+      case "eval_readonly":
+        return { result: this.evaluateReadonly(args) };
+      case "click":
+        return { result: this.click(args) };
+      case "type":
+        return { result: this.type(args) };
+      case "select_element":
+        return { result: this.selectElement(args) };
+      case "wait_for":
+        return { result: await this.waitFor(args) };
+      case "network_probe":
+        return { result: await this.networkProbe(args) };
+      case "apply_artifacts": {
+        const artifacts = parseArtifacts(args.artifacts);
+        return {
+          result: artifacts
+            ? auditResult(this.controller.applyCommandArtifacts(artifacts))
+            : { ok: false, error: "apply_artifacts requires a valid full artifact snapshot." },
+        };
+      }
+      case "navigate": {
+        const rawUrl = string(args.url);
+        try {
+          const url = new URL(rawUrl, this.controller.session.targetOrigin);
+          if (url.origin !== this.controller.session.targetOrigin) {
+            return { result: { ok: false, error: "Navigation must stay on the editor session origin." } };
+          }
+          return {
+            result: { ok: true, url: sanitizedUrl(url.toString()) },
+            afterAcknowledge: () => this.navigation.navigate(url.toString()),
+          };
+        } catch {
+          return { result: { ok: false, error: "Invalid navigation URL" } };
+        }
+      }
+      case "reload":
+        return { result: { ok: true }, afterAcknowledge: () => this.navigation.reload() };
+      case "back":
+        return { result: { ok: true }, afterAcknowledge: () => this.navigation.back() };
+      case "forward":
+        return { result: { ok: true }, afterAcknowledge: () => this.navigation.forward() };
+    }
+  }
+
+  private snapshot(): Record<string, unknown> {
+    const summarize = (selector: string, limit: number) => Array.from(
+      document.querySelectorAll(selector),
+    ).slice(0, limit).map(elementSummary).filter(Boolean);
+    return {
+      title: document.title ? sanitizeDiagnosticText(document.title).slice(0, 220) : null,
+      url: sanitizedUrl(location.href),
+      originalUrl: sanitizedUrl(location.href),
+      bodyTextLength: (document.body.textContent ?? "").length,
+      headings: summarize("h1,h2,h3", 18),
+      interactive: summarize("button,a,input,textarea,select,[role='button'],form", 45),
+      generated: summarize("[data-drip-preview-generated], [class*='apex-'], [class*='abt-'], [class*='drip-']", 20),
+      consoleCount: this.consoleLogs.length,
+      networkCount: this.networkLogs.length,
+    };
+  }
+
+  private click(args: Record<string, unknown>): EditorCommandResult {
+    const target = findTarget(args);
+    if (!target.ok || !target.element) return target as EditorCommandResult;
+    try { target.element.scrollIntoView({ block: "center", inline: "center" }); } catch {}
+    if (target.element instanceof HTMLElement) target.element.click();
+    else target.element.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    return { ok: true, element: elementSummary(target.element), targetResolution: { mode: target.mode } };
+  }
+
+  private type(args: Record<string, unknown>): EditorCommandResult {
+    const target = findTarget(args);
+    if (!target.ok || !target.element) return target as EditorCommandResult;
+    const value = typeof args.value === "string" ? args.value : String(args.value ?? "");
+    if (target.element instanceof HTMLInputElement || target.element instanceof HTMLTextAreaElement || target.element instanceof HTMLSelectElement) {
+      target.element.focus();
+      target.element.value = value;
+    } else if (target.element instanceof HTMLElement && target.element.isContentEditable) {
+      target.element.focus();
+      target.element.textContent = value;
+    } else {
+      return { ok: false, error: "Target does not accept text input" };
+    }
+    target.element.dispatchEvent(new Event("input", { bubbles: true }));
+    target.element.dispatchEvent(new Event("change", { bubbles: true }));
+    return { ok: true, element: elementSummary(target.element), valueLength: value.length };
+  }
+
+  private selectElement(args: Record<string, unknown>): EditorCommandResult {
+    const target = findTarget(args);
+    return target.ok && target.element
+      ? { ok: true, element: elementSummary(target.element), targetResolution: { mode: target.mode } }
+      : target as EditorCommandResult;
+  }
+
+  private async waitFor(args: Record<string, unknown>): Promise<EditorCommandResult> {
+    const timeout = Math.max(100, Math.min(Number(args.timeoutMs) || 5_000, 15_000));
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeout) {
+      const target = findTarget(args);
+      if (target.ok && target.element) {
+        return { ok: true, element: elementSummary(target.element), waitedMs: Date.now() - startedAt };
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return { ok: false, error: "Target not found before timeout", waitedMs: Date.now() - startedAt };
+  }
+
+  private async networkProbe(args: Record<string, unknown>): Promise<EditorCommandResult> {
+    const startIndex = this.networkLogs.length;
+    const waitMs = Math.max(250, Math.min(Number(args.waitMs) || 2_000, 8_000));
+    const action = this.click(args);
+    await new Promise((resolve) => setTimeout(resolve, waitMs));
+    const entries = this.networkLogs.slice(startIndex).slice(-30).map(sanitizeNetworkEntry);
+    return {
+      ok: action.ok,
+      attemptedAction: action.ok,
+      action,
+      waitedMs: waitMs,
+      currentUrl: sanitizedUrl(location.href),
+      originalUrl: sanitizedUrl(location.href),
+      networkObserved: entries.length > 0,
+      successfulRequestCount: entries.length,
+      entries,
+      ...(entries.length ? {} : {
+        repairHint: "No resource request was observed after the action. Inspect the handler and selector, then retry browser_network_probe.",
+      }),
+    };
+  }
+
+  private evaluateReadonly(args: Record<string, unknown>): EditorCommandResult {
+    if (!isLoopbackOrigin(this.controller.session.targetOrigin)) {
+      return {
+        ok: false,
+        error: "eval_readonly is unsupported on live merchant origins.",
+        repairHint: "Use browser_snapshot, browser_select_element, or another allowlisted inspection command.",
+      };
+    }
+    if (string(args.code)) {
+      return {
+        ok: false,
+        error: "JavaScript evaluation is disabled in the merchant SDK runtime.",
+        repairHint: "Pass an allowlisted operation: document_title, current_url, viewport, element_exists, element_count, or element_summary.",
+      };
+    }
+    const operation = string(args.operation);
+    if (operation === "document_title") {
+      return { ok: true, operation, result: sanitizeDiagnosticText(document.title).slice(0, 220) };
+    }
+    if (operation === "current_url") {
+      return { ok: true, operation, result: sanitizedUrl(location.href) };
+    }
+    if (operation === "viewport") {
+      return {
+        ok: true,
+        operation,
+        result: { width: window.innerWidth, height: window.innerHeight },
+      };
+    }
+    if (["element_exists", "element_count", "element_summary"].includes(operation)) {
+      const selector = string(args.selector);
+      if (!selector) return { ok: false, error: `${operation} requires a selector.` };
+      try {
+        const elements = Array.from(document.querySelectorAll(selector));
+        if (operation === "element_exists") {
+          return { ok: true, operation, result: elements.length > 0 };
+        }
+        if (operation === "element_count") {
+          return { ok: true, operation, result: elements.length };
+        }
+        return { ok: true, operation, result: elementSummary(elements[0] ?? null) };
+      } catch {
+        return { ok: false, error: "The inspection selector is invalid." };
+      }
+    }
+    return {
+      ok: false,
+      error: "eval_readonly requires an allowlisted declarative operation.",
+      repairHint: "Use document_title, current_url, viewport, element_exists, element_count, or element_summary.",
+    };
+  }
+}
+
+export class EditorCommandPoller {
+  private running = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private polling = false;
+
+  constructor(
+    private readonly api: EditorApi,
+    private readonly executor: EditorCommandExecutor,
+  ) {}
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.executor.start();
+    void this.poll();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.executor.stop();
+  }
+
+  private async poll(): Promise<void> {
+    if (!this.running || this.polling) return;
+    this.polling = true;
+    try {
+      const commands = await this.api.claimCommands();
+      for (const command of commands) {
+        if (!this.running) break;
+        let execution: CommandExecution;
+        try {
+          execution = await this.executor.execute(command);
+        } catch (error) {
+          await this.api.completeCommand(command.commandId, {
+            error: error instanceof Error ? error.message : "Browser command execution failed",
+          });
+          continue;
+        }
+        await this.api.completeCommand(command.commandId, { result: execution.result });
+        if (execution.afterAcknowledge) {
+          const action = execution.afterAcknowledge;
+          this.stop();
+          setTimeout(action, 0);
+          break;
+        }
+      }
+    } catch (error) {
+      if (error instanceof EditorApiError && [401, 403, 410].includes(error.status)) {
+        this.stop();
+      }
+    } finally {
+      this.polling = false;
+      if (this.running) this.timer = setTimeout(() => void this.poll(), POLL_INTERVAL_MS);
+    }
+  }
+}