@foldspace_npm/harness 0.1.2 → 0.1.3

package/src/action-observer.mjs

@@ -0,0 +1,271 @@
+export const ACTION_OBSERVER_GLOBAL = "__FOLDSPACE_DEV_ACTION_OBSERVER__";
+export const ACTION_LOG_PREFIX = "[foldspace-action]";
+
+export function buildActionObserverScript({
+  agentApiName,
+  mode = "OVERLAY",
+  namespace = "foldspace",
+  maxEvents = 200,
+}) {
+  if (typeof agentApiName !== "string" || !agentApiName) {
+    throw new TypeError("agentApiName is required");
+  }
+  if (!Number.isInteger(maxEvents) || maxEvents < 1 || maxEvents > 1_000) {
+    throw new TypeError("maxEvents must be an integer between 1 and 1000");
+  }
+
+  return `(() => {
+  if (window.top !== window.self) return;
+  const AGENT = ${JSON.stringify(agentApiName)};
+  const MODE = ${JSON.stringify(mode.toUpperCase())};
+  const AGENT_ID = MODE.toLowerCase() + "-" + AGENT;
+  const NS = ${JSON.stringify(namespace)};
+  const MAX_EVENTS = ${maxEvents};
+  const OBSERVER_KEY = ${JSON.stringify(ACTION_OBSERVER_GLOBAL)};
+  const ACTIONS_KEY = "__FOLDSPACE_REMOTE_ACTIONS__";
+  const WRAPPED_MARKER = Symbol("foldspaceHarnessObservedActions");
+  const LOG_PREFIX = ${JSON.stringify(ACTION_LOG_PREFIX)};
+
+  if (window[OBSERVER_KEY]?.version === 1) return;
+
+  const state = {
+    version: 1,
+    targetAgentId: AGENT_ID,
+    expectedActionNames: [],
+    actionNameLimitExceeded: false,
+    captureCount: 0,
+    subscribed: false,
+    events: [],
+    droppedEvents: 0,
+  };
+  window[OBSERVER_KEY] = state;
+
+  const record = (event) => {
+    const safeEvent = { ...event, timestampMs: Date.now() };
+    if (state.events.length >= MAX_EVENTS) {
+      state.events.shift();
+      state.droppedEvents += 1;
+    }
+    state.events.push(safeEvent);
+    try {
+      window.console?.log(LOG_PREFIX + " " + JSON.stringify(safeEvent));
+    } catch {}
+  };
+
+  const parameterKeys = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+    return Object.keys(value)
+      .filter((key) => typeof key === "string")
+      .sort()
+      .slice(0, 50);
+  };
+
+  const now = () => {
+    try { return window.performance?.now?.() ?? Date.now(); }
+    catch { return Date.now(); }
+  };
+
+  const wrapFunction = (actionName, phase, fn) =>
+    function observedActionPhase(...args) {
+      const startedAt = now();
+      record({
+        source: "local-handler",
+        actionName,
+        phase,
+        status: "started",
+        ...(phase === "execute"
+          ? { parameterKeys: parameterKeys(args[0]) }
+          : {}),
+      });
+
+      const succeeded = (value) => {
+        record({
+          source: "local-handler",
+          actionName,
+          phase,
+          status: "succeeded",
+          durationMs: Math.max(0, Math.round(now() - startedAt)),
+        });
+        return value;
+      };
+      const failed = (error) => {
+        record({
+          source: "local-handler",
+          actionName,
+          phase,
+          status: "failed",
+          durationMs: Math.max(0, Math.round(now() - startedAt)),
+          errorName:
+            typeof error?.name === "string"
+              ? error.name.slice(0, 100)
+              : "Error",
+        });
+        throw error;
+      };
+
+      try {
+        const value = Reflect.apply(fn, this, args);
+        return value && typeof value.then === "function"
+          ? Promise.resolve(value).then(succeeded, failed)
+          : succeeded(value);
+      } catch (error) {
+        return failed(error);
+      }
+    };
+
+  const wrapHandlers = (handlers) => {
+    if (!handlers || typeof handlers !== "object") return handlers;
+    if (handlers[WRAPPED_MARKER] === true) return handlers;
+
+    const allNames = Object.keys(handlers)
+      .filter((name) => typeof name === "string")
+      .sort();
+    const names = allNames.slice(0, 200);
+    const descriptors = Object.getOwnPropertyDescriptors(handlers);
+    for (const name of names) {
+      const descriptor = descriptors[name];
+      const definition =
+        descriptor && "value" in descriptor
+          ? descriptor.value
+          : handlers[name];
+      if (!definition || typeof definition !== "object") {
+        continue;
+      }
+      const actionDescriptors = Object.getOwnPropertyDescriptors(definition);
+      for (const phase of ["execute", "render"]) {
+        const phaseDescriptor = actionDescriptors[phase];
+        if (
+          phaseDescriptor &&
+          "value" in phaseDescriptor &&
+          typeof phaseDescriptor.value === "function"
+        ) {
+          actionDescriptors[phase] = {
+            ...phaseDescriptor,
+            value: wrapFunction(name, phase, phaseDescriptor.value),
+          };
+        }
+      }
+      if (!descriptor || !("value" in descriptor)) continue;
+      const observedDefinition = Object.create(
+        Object.getPrototypeOf(definition),
+        actionDescriptors,
+      );
+      if (!Object.isExtensible(definition)) {
+        Object.preventExtensions(observedDefinition);
+      }
+      descriptors[name] = {
+        ...descriptor,
+        value: observedDefinition,
+      };
+    }
+    const wrapped = Object.create(
+      Object.getPrototypeOf(handlers),
+      descriptors,
+    );
+    Object.defineProperty(wrapped, WRAPPED_MARKER, {
+      value: true,
+      enumerable: false,
+    });
+    state.expectedActionNames = names;
+    state.actionNameLimitExceeded = allNames.length > names.length;
+    state.captureCount += 1;
+    record({
+      source: "harness",
+      phase: "registration",
+      status: names.length ? "captured" : "empty",
+      actionNames: names,
+    });
+    return wrapped;
+  };
+
+  let currentActions;
+  const getCurrentActions = () => currentActions;
+  const setCurrentActions = (handlers) => {
+    currentActions = wrapHandlers(handlers);
+  };
+  const ensureActionCapture = () => {
+    const descriptor = Object.getOwnPropertyDescriptor(window, ACTIONS_KEY);
+    if (descriptor?.get === getCurrentActions) return;
+    currentActions =
+      descriptor && "value" in descriptor
+        ? wrapHandlers(descriptor.value)
+        : undefined;
+    try {
+      Object.defineProperty(window, ACTIONS_KEY, {
+        configurable: true,
+        enumerable: true,
+        get: getCurrentActions,
+        set: setCurrentActions,
+      });
+    } catch {
+      record({
+        source: "harness",
+        phase: "registration",
+        status: "capture_failed",
+      });
+    }
+  };
+  ensureActionCapture();
+
+  const observedAgents = new WeakSet();
+  const subscribe = () => {
+    ensureActionCapture();
+    const sdk = window[NS];
+    if (!sdk || typeof sdk.agent !== "function") return;
+    let ids = [];
+    try { ids = typeof sdk.agentIds === "function" ? sdk.agentIds() : []; }
+    catch {}
+    if (!ids.includes(AGENT_ID)) return;
+
+    let agent;
+    try { agent = sdk.agent({ apiName: AGENT, mode: MODE }); }
+    catch { return; }
+    if (!agent || observedAgents.has(agent)) return;
+    observedAgents.add(agent);
+
+    try {
+      const recordSdkAction = (event) => {
+        record({
+          source: "sdk",
+          actionName:
+            typeof event?.actionKey === "string"
+              ? event.actionKey.slice(0, 200)
+              : "unknown",
+          phase: "action",
+          status:
+            typeof event?.status === "string"
+              ? event.status.slice(0, 100)
+              : "unknown",
+        });
+      };
+      agent.on?.("action.callback", recordSdkAction);
+      agent.on?.("remoteActions.loaded", ensureActionCapture);
+      agent.on?.("remoteActions.failed", ensureActionCapture);
+      state.subscribed = true;
+      const widget = window.document?.querySelector?.("#eucera-agent-view");
+      widget?.setAttribute?.("data-foldspace-dev-agent-id", AGENT_ID);
+    } catch {
+      state.subscribed = false;
+    }
+  };
+
+  const arm = () => {
+    try { window[NS]?.("when", "ready", subscribe); } catch {}
+    subscribe();
+    setInterval(subscribe, 1000);
+  };
+
+  if (window[NS]) arm();
+  else {
+    let attempts = 0;
+    const timer = setInterval(() => {
+      if (window[NS]) {
+        clearInterval(timer);
+        arm();
+      } else if (++attempts > 200) {
+        clearInterval(timer);
+      }
+    }, 50);
+  }
+})();`;
+}

package/src/attach-helpers.mjs

@@ -0,0 +1,162 @@
+export const ATTACH_MODES = Object.freeze({
+  SWAP: "swap",
+  BOOTSTRAP: "bootstrap",
+  REPLACE: "replace",
+});
+
+export function attachModeFromArgs(argv) {
+  const bootstrap = argv.includes("--bootstrap");
+  const replace = argv.includes("--replace");
+  if (bootstrap && replace) {
+    throw new Error("--bootstrap and --replace cannot be used together");
+  }
+  if (bootstrap) return ATTACH_MODES.BOOTSTRAP;
+  if (replace) return ATTACH_MODES.REPLACE;
+  return ATTACH_MODES.SWAP;
+}
+
+export function hostPatternsFromMatches(matches) {
+  return matches.map((match) =>
+    match.replace("*://", "").replace("/*", ""),
+  );
+}
+
+export function hostPatternsFromTarget(target = {}) {
+  if (Array.isArray(target.hosts) && target.hosts.length) {
+    return target.hosts
+      .filter((host) => typeof host === "string" && host.trim())
+      .map((host) => host.trim().replace(/^\*:\/\//, "").replace(/\/\*$/, ""));
+  }
+  if (typeof target.startUrl !== "string" || !target.startUrl) return [];
+  try {
+    const { hostname } = new URL(target.startUrl);
+    return hostname ? [hostname] : [];
+  } catch {
+    return [];
+  }
+}
+
+export function hostMatches(url, hostPatterns) {
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return false;
+  }
+  return hostPatterns.some((pattern) =>
+    pattern.startsWith("*.")
+      ? hostname === pattern.slice(2) || hostname.endsWith(pattern.slice(1))
+      : hostname === pattern,
+  );
+}
+
+export function parseAgentId(agentId) {
+  if (typeof agentId !== "string") return null;
+  const separator = agentId.indexOf("-");
+  if (separator < 1 || separator === agentId.length - 1) return null;
+  return {
+    id: agentId,
+    mode: agentId.slice(0, separator).toUpperCase(),
+    apiName: agentId.slice(separator + 1),
+  };
+}
+
+export function characterizePageAgents({
+  sdkPresent,
+  agentIds = [],
+  expectedApiName,
+  expectedMode = "OVERLAY",
+}) {
+  const parsedAgents = agentIds
+    .map(parseAgentId)
+    .filter(Boolean)
+    .slice(0, 50);
+  const matchingAgents = parsedAgents.filter(
+    (agent) =>
+      agent.apiName === expectedApiName &&
+      agent.mode === expectedMode.toUpperCase(),
+  );
+
+  let status;
+  if (!sdkPresent) {
+    status = "no-sdk";
+  } else if (parsedAgents.length === 0) {
+    status = "sdk-without-agent";
+  } else if (matchingAgents.length === 0) {
+    status = "different-agent";
+  } else if (parsedAgents.length === 1) {
+    status = "same-agent";
+  } else {
+    status = "multiple-agents";
+  }
+
+  return {
+    status,
+    expectedAgentId: `${expectedMode.toLowerCase()}-${expectedApiName}`,
+    agents: parsedAgents,
+    matchingAgentIds: matchingAgents.map((agent) => agent.id),
+  };
+}
+
+export function parseActionRequest(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  const agentIndex = segments.findIndex(
+    (segment, index) =>
+      segment === "agent" && segments[index + 1] === "actions",
+  );
+  if (agentIndex < 0 || segments.length < agentIndex + 6) {
+    return null;
+  }
+
+  const [environment, productId, agentApiName, ...artifactSegments] =
+    segments.slice(agentIndex + 2);
+  if (!environment || !productId || !agentApiName || !artifactSegments.length) {
+    return null;
+  }
+
+  try {
+    return {
+      environment: decodeURIComponent(environment).toUpperCase(),
+      productId: decodeURIComponent(productId),
+      agentApiName: decodeURIComponent(agentApiName),
+      artifactPath: artifactSegments.map(decodeURIComponent).join("/"),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function actionRequestMatchesTarget(request, target) {
+  return Boolean(
+    request &&
+      request.productId === target.productId &&
+      request.agentApiName === target.agentApiName,
+  );
+}
+
+export function summarizeConsoleMessages(messages, limit = 50) {
+  const summaries = new Map();
+  for (const message of messages) {
+    const text = String(message?.text ?? message ?? "")
+      .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "<id>")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, 1_000);
+    if (!text) continue;
+    const level = String(message?.level || "log").toLowerCase();
+    const key = `${level}:${text}`;
+    const existing = summaries.get(key);
+    if (existing) {
+      existing.count += 1;
+    } else if (summaries.size < limit) {
+      summaries.set(key, { level, text, count: 1 });
+    }
+  }
+  return Array.from(summaries.values());
+}