@foldspace_npm/harness 0.1.2 → 0.1.3

package/src/attach-preflight.mjs

@@ -0,0 +1,332 @@
+import {
+  ATTACH_MODES,
+  actionRequestMatchesTarget,
+  parseActionRequest,
+} from "./attach-helpers.mjs";
+import { ERROR_CODES } from "./protocol.mjs";
+
+export function productIdFromAgentKey(key) {
+  if (typeof key !== "string") return null;
+  const match = key.match(/^EU-([A-Za-z0-9_]+)-\d+-\d+$/);
+  return match?.[1] || null;
+}
+
+export function detectedProductIds(sdkState) {
+  const keys = [sdkState?.trackerKey, sdkState?.sdkKey];
+  for (const source of sdkState?.scripts || []) {
+    try {
+      keys.push(new URL(source).searchParams.get("k"));
+    } catch {
+      // Ignore malformed script URLs reported by the page.
+    }
+  }
+  return [
+    ...new Set(keys.map(productIdFromAgentKey).filter(Boolean)),
+  ];
+}
+
+export function guardAttachMode({
+  mode,
+  characterization,
+  expectedProductId,
+  pageProductIds = [],
+}) {
+  const productMismatch =
+    pageProductIds.length > 0 &&
+    !pageProductIds.includes(expectedProductId);
+
+  if (mode === ATTACH_MODES.BOOTSTRAP) {
+    if (characterization.status === "no-sdk") {
+      return { ok: true, mode };
+    }
+    return {
+      ok: false,
+      mode,
+      code: ERROR_CODES.REGISTRATION_MISMATCH,
+      message: "Bootstrap mode requires a page without the Foldspace SDK.",
+      suggestion:
+        characterization.status === "same-agent"
+          ? "Use swap mode without --bootstrap."
+          : "Use --replace to make the configured agent own the page.",
+    };
+  }
+
+  if (mode === ATTACH_MODES.SWAP) {
+    if (characterization.status === "no-sdk") {
+      return {
+        ok: false,
+        mode,
+        code: ERROR_CODES.SDK_NOT_FOUND,
+        message: "Swap mode requires an existing Foldspace SDK and agent.",
+        suggestion: "Use --bootstrap when the page does not embed Foldspace.",
+      };
+    }
+    if (characterization.status !== "same-agent") {
+      return {
+        ok: false,
+        mode,
+        code: ERROR_CODES.REGISTRATION_MISMATCH,
+        message:
+          "Swap mode requires exactly the configured agent on the page.",
+        suggestion:
+          "Use --replace when the page embeds a different agent, or close duplicate agent instances.",
+      };
+    }
+    if (pageProductIds.length === 0) {
+      return {
+        ok: false,
+        mode,
+        code: ERROR_CODES.REGISTRATION_MISMATCH,
+        message:
+          "Swap mode could not verify which product owns the page agent.",
+        suggestion:
+          "Use --replace, or update the page SDK so its tracker key is inspectable.",
+      };
+    }
+    if (productMismatch) {
+      return {
+        ok: false,
+        mode,
+        code: ERROR_CODES.REGISTRATION_MISMATCH,
+        message:
+          "The page agent API name matches, but its product does not match the configured product.",
+        suggestion: "Use --replace for a cross-product development session.",
+      };
+    }
+    return { ok: true, mode };
+  }
+
+  if (mode === ATTACH_MODES.REPLACE) {
+    if (characterization.status === "no-sdk") {
+      return {
+        ok: false,
+        mode,
+        code: ERROR_CODES.SDK_NOT_FOUND,
+        message: "Replace mode requires a page-provided Foldspace SDK bootstrap.",
+        suggestion: "Use --bootstrap when the page does not embed Foldspace.",
+      };
+    }
+    return { ok: true, mode };
+  }
+
+  return {
+    ok: false,
+    mode,
+    code: ERROR_CODES.INVALID_REQUEST,
+    message: `Unknown attach mode: ${mode}`,
+  };
+}
+
+export function shouldFulfillActionRequest(url, target) {
+  return actionRequestMatchesTarget(parseActionRequest(url), target);
+}
+
+function sdkScriptIdentity(url) {
+  try {
+    const parsed = new URL(url);
+    if (
+      parsed.protocol !== "https:" ||
+      parsed.hostname !== "script.eucerahive.io" ||
+      !/^\/web\/sdk\/(?:foldspace|eucera)\.js$/i.test(parsed.pathname)
+    ) {
+      return null;
+    }
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return null;
+  }
+}
+
+export function isSdkScriptRequest(url, allowedSdkUrls = []) {
+  const identity = sdkScriptIdentity(url);
+  if (!identity) return false;
+  const allowedIdentities = allowedSdkUrls
+    .map(sdkScriptIdentity)
+    .filter(Boolean);
+  return (
+    allowedIdentities.length === 0 || allowedIdentities.includes(identity)
+  );
+}
+
+export function rewriteSdkRequestKey(url, agentKey, allowedSdkUrls = []) {
+  if (!isSdkScriptRequest(url, allowedSdkUrls)) return null;
+  const rewritten = new URL(url);
+  rewritten.searchParams.set("k", agentKey);
+  return rewritten.toString();
+}
+
+export function guardScriptForHosts(source, hostPatterns) {
+  return `(() => {
+  const hostname = window.location?.hostname || "";
+  const allowed = ${JSON.stringify(hostPatterns)}.some((pattern) =>
+    pattern.startsWith("*.")
+      ? hostname === pattern.slice(2) || hostname.endsWith(pattern.slice(1))
+      : hostname === pattern
+  );
+  if (!allowed) return;
+  ${source}
+})();`;
+}
+
+export function buildReplacePrelude({
+  agentKey,
+  agentApiName,
+  mode = "OVERLAY",
+  namespace = "foldspace",
+  aliases = [],
+}) {
+  const source = `(() => {
+  if (window.top !== window.self) return;
+  const KEY = ${JSON.stringify(agentKey)};
+  const TARGET = ${JSON.stringify(agentApiName)};
+  const MODE = ${JSON.stringify(mode.toUpperCase())};
+  const TARGET_ID = MODE.toLowerCase() + "-" + TARGET;
+  const ALIASES = new Set(${JSON.stringify(
+    [...new Set(aliases.filter((alias) => alias && alias !== agentApiName))],
+  )});
+  const NS = ${JSON.stringify(namespace)};
+
+  const stub = typeof window[NS] === "function"
+    ? window[NS]
+    : function () { (stub.q = stub.q || []).push(arguments); };
+  stub.q = stub.q || [];
+  try {
+    Object.defineProperty(stub, "k", {
+      configurable: true,
+      enumerable: true,
+      get: () => KEY,
+      set: () => {},
+    });
+  } catch {
+    stub.k = KEY;
+  }
+  window.__FOLD_SPACE__ = NS;
+  window[NS] = stub;
+
+  stub("when", "ready", () => {
+    const fs = window[NS];
+    if (!fs || typeof fs.agent !== "function") return;
+    const originalAgent = fs.agent.bind(fs);
+    let target = null;
+    let rawAddHandlers = null;
+    const aliasFacades = new Map();
+
+    const splitId = (id) => {
+      const cut = typeof id === "string" ? id.indexOf("-") : -1;
+      return cut > 0
+        ? { mode: id.slice(0, cut).toUpperCase(), apiName: id.slice(cut + 1) }
+        : null;
+    };
+
+    const removeOtherAgents = () => {
+      let ids = [];
+      try { ids = typeof fs.agentIds === "function" ? fs.agentIds() : []; }
+      catch {}
+      for (const id of ids) {
+        const parsed = splitId(id);
+        if (!parsed || (parsed.apiName === TARGET && parsed.mode === MODE)) continue;
+        try { originalAgent(parsed)?.remove?.(); } catch {}
+      }
+    };
+
+    const ensureTarget = () => {
+      removeOtherAgents();
+      if (!target) {
+        target = originalAgent({
+          apiName: TARGET,
+          mode: MODE,
+          configuration: { enableDebugLogs: true },
+        });
+        window.__FOLDSPACE_AGENT__ = target;
+      }
+      if (!target) return null;
+
+      const localActions = window.__FOLDSPACE_REMOTE_ACTIONS__;
+      if (!rawAddHandlers && typeof target.addActionHandlers === "function") {
+        rawAddHandlers = target.addActionHandlers.bind(target);
+        target.addActionHandlers = (handlers) => {
+          const result = rawAddHandlers(handlers);
+          const currentLocal = window.__FOLDSPACE_REMOTE_ACTIONS__;
+          if (handlers !== currentLocal && currentLocal) {
+            setTimeout(() => rawAddHandlers(currentLocal), 0);
+          }
+          return result;
+        };
+      }
+      try { if (localActions && rawAddHandlers) rawAddHandlers(localActions); }
+      catch {}
+      try { target.setTestMode?.(true); } catch {}
+      try { target.show?.(); } catch {}
+      try { target.open?.(); } catch {}
+      // A regular extension can intentionally hide the SDK view while its own
+      // dock is closed. Explicit replace mode owns visibility, so override only
+      // that external display:none rule for the lifetime of this document.
+      if (MODE === "OVERLAY") {
+        try {
+          const widget = window.document?.querySelector?.("#eucera-agent-view");
+          if (
+            widget &&
+            window.getComputedStyle?.(widget)?.display === "none"
+          ) {
+            widget.style.setProperty("display", "block", "important");
+          }
+          widget?.setAttribute?.(
+            "data-foldspace-dev-agent-id",
+            TARGET_ID,
+          );
+        } catch {}
+      }
+      return target;
+    };
+
+    const aliasFacade = (alias, selected) => {
+      if (aliasFacades.has(alias)) return aliasFacades.get(alias);
+      let facade;
+      facade = new Proxy(selected, {
+        get(object, property) {
+          if (property === "addActionHandlers") {
+            return () => facade;
+          }
+          if (
+            property === "hide" ||
+            property === "close" ||
+            property === "remove"
+          ) {
+            return () => facade;
+          }
+          const value = Reflect.get(object, property, object);
+          return typeof value === "function" ? value.bind(object) : value;
+        },
+      });
+      aliasFacades.set(alias, facade);
+      return facade;
+    };
+
+    fs.agent = (settings) => {
+      const requested =
+        typeof settings === "string" ? settings : settings?.apiName;
+      if (!requested) return originalAgent(settings);
+      const selected = ensureTarget();
+      setTimeout(ensureTarget, 0);
+      return selected ? aliasFacade(requested, selected) : selected;
+    };
+
+    ensureTarget();
+    setTimeout(ensureTarget, 0);
+    setInterval(ensureTarget, 1000);
+    window.__FOLDSPACE_DEV_REPLACE__ = {
+      agentApiName: TARGET,
+      mode: MODE,
+      aliases: Array.from(ALIASES),
+      key: KEY,
+    };
+    console.log("[foldspace-dev] replacement active", {
+      agent: TARGET,
+      mode: MODE,
+      aliases: Array.from(ALIASES),
+    });
+  });
+})();`;
+
+  return source;
+}

package/src/bootstrap-script.mjs

@@ -0,0 +1,120 @@
+export function buildBootstrapScript({
+  sdkUrl,
+  productId,
+  agentApiName,
+  mode = "OVERLAY",
+  overrideKey = null,
+  namespace = "foldspace",
+}) {
+  for (const [name, value] of Object.entries({
+    sdkUrl,
+    productId,
+    agentApiName,
+  })) {
+    if (typeof value !== "string" || !value) {
+      throw new TypeError(`${name} is required`);
+    }
+  }
+
+  return `(() => {
+  if (window.top !== window.self) return;
+  const SDK_URL = ${JSON.stringify(sdkUrl)};
+  const PRODUCT_ID = ${JSON.stringify(productId)};
+  const AGENT_API_NAME = ${JSON.stringify(agentApiName)};
+  const MODE = ${JSON.stringify(String(mode).toUpperCase())};
+  const OVERRIDE_KEY = ${JSON.stringify(overrideKey)};
+  const NAMESPACE = ${JSON.stringify(namespace)};
+
+  const sdkLoaded = () =>
+    typeof window[NAMESPACE] === "function" &&
+    typeof window[NAMESPACE].agent === "function";
+
+  const appendSdkScript = () => {
+    const key = OVERRIDE_KEY || ("EU-" + PRODUCT_ID + "-1-1");
+    window[NAMESPACE] =
+      window[NAMESPACE] ||
+      function foldspaceQueue() {
+        (window[NAMESPACE].q = window[NAMESPACE].q || []).push(arguments);
+      };
+    window.__FOLD_SPACE__ = NAMESPACE;
+    window[NAMESPACE].k = key;
+    if (document.querySelector("script[data-foldspace-sdk]")) return;
+    if (!document.body) throw new Error("document.body not ready");
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = SDK_URL + "?k=" + encodeURIComponent(key);
+    script.setAttribute("data-foldspace-sdk", "1");
+    const first = document.getElementsByTagName("script")[0];
+    if (first?.parentNode) first.parentNode.insertBefore(script, first);
+    else (document.head || document.documentElement).appendChild(script);
+  };
+
+  const tryAppendSdkScript = () => {
+    try { appendSdkScript(); } catch {}
+  };
+
+  if (!sdkLoaded()) {
+    let attempts = 0;
+    const retry = setInterval(() => {
+      if (sdkLoaded() || ++attempts > 60) {
+        clearInterval(retry);
+        return;
+      }
+      tryAppendSdkScript();
+    }, 250);
+    document.addEventListener("DOMContentLoaded", tryAppendSdkScript);
+    tryAppendSdkScript();
+  }
+
+  let initialized = false;
+  const initializeAgent = () => {
+    if (initialized) return;
+    const sdk = window[NAMESPACE];
+    if (typeof sdk?.agent !== "function") return;
+    initialized = true;
+    const configuration = { enableDebugLogs: true };
+    if (MODE === "EMBEDDED") {
+      let container = document.getElementById("foldspace-container");
+      if (!container) {
+        container = document.createElement("div");
+        container.id = "foldspace-container";
+        document.body.appendChild(container);
+      }
+      configuration.embeddedConfiguration = { container };
+    }
+
+    const agent = sdk.agent({
+      apiName: AGENT_API_NAME,
+      mode: MODE,
+      configuration,
+    });
+    window.__FOLDSPACE_AGENT__ = agent;
+
+    let attachedActions = null;
+    const attachActions = () => {
+      const actions = window.__FOLDSPACE_REMOTE_ACTIONS__;
+      if (!actions || actions === attachedActions) return;
+      agent.addActionHandlers(actions);
+      attachedActions = actions;
+      delete window.__FOLDSPACE_REMOTE_ACTIONS__;
+      console.log(
+        "[foldspace-dev] actions attached:",
+        Object.keys(actions).length,
+      );
+    };
+    agent.on?.("*", (event) => {
+      if (event?.eventName === "agent.ready") attachActions();
+    });
+    attachActions();
+    setTimeout(attachActions, 0);
+  };
+
+  try { window[NAMESPACE]("when", "ready", initializeAgent); } catch {}
+  try { if (sdkLoaded()) initializeAgent(); } catch {}
+  console.log("[foldspace-dev] bootstrap queued", {
+    agent: AGENT_API_NAME,
+    product: PRODUCT_ID,
+    mode: MODE,
+  });
+})();`;
+}

package/src/cdp-request-manager.mjs

@@ -0,0 +1,61 @@
+export function createCdpRequestManager({ timeoutMs = 10_000 } = {}) {
+  let nextId = 1;
+  const pending = new Map();
+
+  function call(socket, method, params = {}, sessionId) {
+    return new Promise((resolve, reject) => {
+      if (!socket || socket.readyState !== 1) {
+        reject(new Error(`CDP socket is not open for ${method}`));
+        return;
+      }
+
+      const id = nextId++;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`CDP ${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      pending.set(id, { method, resolve, reject, timer });
+
+      try {
+        socket.send(JSON.stringify({ id, method, params, sessionId }));
+      } catch (error) {
+        clearTimeout(timer);
+        pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  function handleMessage(message) {
+    const request = pending.get(message?.id);
+    if (!request) return false;
+
+    clearTimeout(request.timer);
+    pending.delete(message.id);
+    if (message.error) {
+      const error = new Error(
+        `CDP ${request.method} failed: ${message.error.message || "Unknown error"}`,
+      );
+      error.code = message.error.code;
+      request.reject(error);
+    } else {
+      request.resolve(message.result);
+    }
+    return true;
+  }
+
+  function failAll(error = new Error("CDP socket closed")) {
+    for (const request of pending.values()) {
+      clearTimeout(request.timer);
+      request.reject(error);
+    }
+    pending.clear();
+  }
+
+  return {
+    call,
+    handleMessage,
+    failAll,
+    pendingCount: () => pending.size,
+  };
+}

package/src/cli-help.mjs

@@ -0,0 +1,143 @@
+const GROUPS = [
+  ["start", "Start an actions project"],
+  ["develop", "Build the portable artifact"],
+  ["verify", "Verify against a live application"],
+  ["publish", "Publish explicitly"],
+];
+
+function rows(entries) {
+  const width = Math.max(...entries.map(([label]) => label.length), 0);
+  return entries
+    .map(([label, description]) => `  ${label.padEnd(width)}  ${description}`)
+    .join("\n");
+}
+
+export function renderGeneralHelp(registry) {
+  const sections = [
+    "usage: foldspace [--help | --version] <command> [<args>]",
+    "",
+    "Build and verify a portable Foldspace action artifact.",
+    "",
+    "Typical local workflow:",
+    "  foldspace init <directory>",
+    "  foldspace build",
+    "  foldspace inject",
+    "  foldspace attach",
+  ];
+
+  for (const [group, title] of GROUPS) {
+    const commands = registry.commands
+      .filter((command) => command.group === group)
+      .map((command) => [command.name, command.summary]);
+    if (!commands.length) continue;
+    sections.push("", `${title}:`, rows(commands));
+  }
+
+  sections.push(
+    "",
+    "Choose an attach mode:",
+    "  swap       Default. The page already has the configured product and agent.",
+    "  bootstrap  Use --bootstrap only when the page has no Foldspace SDK.",
+    "  replace    Use --replace for a different page product or agent.",
+    "",
+    "Discovery:",
+    "  foldspace help <command>         Show command-specific guidance",
+    "  foldspace <command> --help       Same command-specific guidance",
+    "  foldspace help --json            Print the machine-readable CLI contract",
+    "  foldspace help <command> --json  Print one command contract",
+    "  foldspace --version              Show package and protocol versions",
+    "",
+    "attach loads local actions and observes the normal agent experience.",
+    "deploy is a separate remote publication step.",
+  );
+  return sections.join("\n");
+}
+
+export function renderCommandHelp(registry, name) {
+  const command = registry.commands.find((entry) => entry.name === name);
+  if (!command) return null;
+  const sections = [
+    `usage: ${command.usage}`,
+    "",
+    command.summary,
+    "",
+    `Risk: ${command.risk} — ${
+      registry.risks.find(({ id }) => id === command.risk)?.description || ""
+    }`,
+    `Environment: ${command.environment} — ${
+      registry.environments.find(({ id }) => id === command.environment)
+        ?.description || ""
+    }`,
+  ];
+  if (command.options.length) {
+    const optionRows = command.options.map((option) => [
+      `${option.name}${option.value ? ` <${option.value}>` : ""}`,
+      `${option.description}${
+        option.default ? ` (default: ${option.default})` : ""
+      }`,
+    ]);
+    sections.push("", "Options:", rows(optionRows));
+  }
+  if (command.modes?.length) {
+    sections.push(
+      "",
+      "Modes:",
+      rows(
+        command.modes.map((mode) => [
+          mode.flag || mode.name,
+          mode.description,
+        ]),
+      ),
+    );
+  }
+  if (command.environmentVariables.length) {
+    sections.push(
+      "",
+      "Environment variables:",
+      ...command.environmentVariables.map((name) => `  - ${name}`),
+    );
+  }
+  if (command.prerequisites.length) {
+    sections.push(
+      "",
+      "Prerequisites:",
+      ...command.prerequisites.map((item) => `  - ${item}`),
+    );
+  }
+  if (command.effects.length) {
+    sections.push(
+      "",
+      "Effects:",
+      ...command.effects.map((item) => `  - ${item}`),
+    );
+  }
+  if (command.next.length) {
+    sections.push(
+      "",
+      "Next:",
+      ...command.next.map((item) => `  - ${item}`),
+    );
+  }
+  return sections.join("\n");
+}
+
+export function helpDocument(registry, topic) {
+  if (!topic) return registry;
+  const command = registry.commands.find((entry) => entry.name === topic);
+  if (!command) return null;
+  return {
+    kind: "foldspace.cli.command",
+    schemaVersion: registry.schemaVersion,
+    package: registry.package,
+    protocolVersion: registry.protocolVersion,
+    command,
+    risk: registry.risks.find(({ id }) => id === command.risk),
+    environment: registry.environments.find(
+      ({ id }) => id === command.environment,
+    ),
+    capabilities: registry.capabilities.filter((capability) =>
+      command.capabilities.includes(capability.id),
+    ),
+    diagnostics: command.name === "attach" ? registry.diagnostics : [],
+  };
+}