@foldspace_npm/harness 0.1.0

package/bin/inject.mjs

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+/**
+ * Local Foldspace injector.
+ *
+ * Generates a throwaway Chrome extension for a target app and launches Chrome
+ * with it loaded, so you can exercise agent actions against a live site without
+ * touching the committed production extension in extension/.
+ *
+ *   npm run inject                                  # default target
+ *   npm run inject -- --target app
+ *   npm run inject -- --url https://app.other.com --product ABC123 --agent other-agent
+ *   npm run inject -- --remote                      # use deployed actions, not localhost
+ *   npm run inject -- --print                       # generate only, don't launch
+ */
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Resolve the CONSUMING repo, not this package. FOLDSPACE_PROJECT_DIR lets a
+// hosted builder point the harness at a workspace it controls.
+const root = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
+const workDir = path.join(root, ".foldspace-dev");
+const extDir = path.join(workDir, "extension");
+const themeDir = path.join(workDir, "theme-extension");
+const profileDir = path.join(workDir, "chrome-profile");
+
+// ---------------------------------------------------------------- args
+
+function parseArgs(argv) {
+  const out = { flags: new Set() };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--remote") out.flags.add("remote");
+    else if (a === "--print") out.flags.add("print");
+    else if (a === "--embedded") out.flags.add("embedded");
+    else if (a.startsWith("--")) out[a.slice(2)] = argv[++i];
+  }
+  return out;
+}
+const args = parseArgs(process.argv.slice(2));
+
+// ---------------------------------------------------------------- config
+
+const configPath = path.join(root, "foldspace.dev.json");
+if (!fs.existsSync(configPath)) {
+  console.error("Missing foldspace.dev.json at project root.");
+  process.exit(1);
+}
+const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+const targetName = args.target || cfg.defaultTarget;
+const base = cfg.targets[targetName] || {};
+
+if (!args.url && !base.startUrl) {
+  console.error(
+    `Unknown target "${targetName}". Add it to foldspace.dev.json, or pass --url/--product/--agent.`
+  );
+  process.exit(1);
+}
+
+const startUrl = args.url || base.startUrl;
+
+// Derive host patterns from the URL when not configured — registrable domain + wildcard.
+function hostsFor(urlStr, configured) {
+  if (configured && configured.length) return configured;
+  const { hostname } = new URL(urlStr);
+  const parts = hostname.split(".");
+  const apex = parts.length > 2 ? parts.slice(-2).join(".") : hostname;
+  return [apex, `*.${apex}`];
+}
+
+// A --url with no --target means we are pointing at an app the config does not
+// describe, so the named target's ids and host patterns must not leak in.
+// Passing --target as well keeps that target's config and just moves the start URL.
+const explicitUrl = Boolean(args.url) && !args.target;
+const configuredHosts = args.hosts
+  ? args.hosts.split(",")
+  : explicitUrl
+    ? null
+    : base.hosts;
+
+const target = {
+  name: explicitUrl && !args.target ? new URL(startUrl).hostname : targetName,
+  startUrl,
+  productId: args.product || (explicitUrl ? null : base.productId),
+  agentApiName: args.agent || (explicitUrl ? null : base.agentApiName),
+  hosts: hostsFor(startUrl, configuredHosts),
+  mode: args.flags.has("embedded") ? "EMBEDDED" : base.mode || "OVERLAY",
+  loadLocally: args.flags.has("remote") ? false : base.loadLocally !== false,
+  overrideKey: args.key || base.overrideKey || null,
+  remoteActionsEnv: args.env || base.remoteActionsEnv || "PROD",
+};
+
+for (const required of ["productId", "agentApiName"]) {
+  if (!target[required]) {
+    console.error(`Missing ${required}. Pass --product / --agent or add it to foldspace.dev.json.`);
+    process.exit(1);
+  }
+}
+
+const sdkUrl = cfg.sdkUrl;
+const localActionsUrl = cfg.localActionsUrl || "http://localhost:3007/dist/index.js";
+const matches = target.hosts.map((h) => `*://${h}/*`);
+const requestDomains = [...new Set(target.hosts.map((h) => h.replace(/^\*\./, "")))];
+const scriptHost = new URL(sdkUrl).hostname;
+
+// ---------------------------------------------------------------- generate
+
+fs.rmSync(extDir, { recursive: true, force: true });
+fs.mkdirSync(extDir, { recursive: true });
+
+// A theme-only extension, regenerated each run so it survives `rm -rf
+// .foldspace-dev`. Purely cosmetic: it paints the dev browser Foldspace blue so
+// the window is never mistaken for the user's own Chrome. Chrome ignores
+// hand-edited theme keys in Preferences, but honours a theme extension.
+fs.rmSync(themeDir, { recursive: true, force: true });
+fs.mkdirSync(themeDir, { recursive: true });
+fs.writeFileSync(
+  path.join(themeDir, "manifest.json"),
+  JSON.stringify({
+    manifest_version: 3,
+    name: "Foldspace Dev Theme",
+    version: "1.0",
+    description: "Paints the dev browser Foldspace blue.",
+    theme: {
+      colors: {
+        frame: [50, 71, 242],
+        frame_inactive: [70, 89, 235],
+        toolbar: [50, 71, 242],
+        tab_background_text: [214, 220, 255],
+        tab_text: [255, 255, 255],
+        bookmark_text: [255, 255, 255],
+        ntp_background: [16, 22, 60],
+        ntp_text: [255, 255, 255],
+        omnibox_background: [28, 38, 110],
+        omnibox_text: [255, 255, 255],
+      },
+      tints: { buttons: [-1.0, -1.0, 1.0] },
+    },
+  }, null, 2),
+);
+
+const manifest = {
+  manifest_version: 3,
+  name: `Foldspace Dev — ${target.name}`,
+  version: "0.0.1",
+  description: `Local Foldspace injection for ${target.agentApiName}`,
+  permissions: [
+    "scripting",
+    "activeTab",
+    "tabs",
+    "declarativeNetRequest",
+    "declarativeNetRequestWithHostAccess",
+  ],
+  host_permissions: [...matches, "http://localhost/*", `https://${scriptHost}/*`],
+  declarative_net_request: {
+    rule_resources: [{ id: "csp_bypass_rules", enabled: true, path: "csp_rules.json" }],
+  },
+  ...(fs.existsSync(path.join(root, "extension", "logo.png"))
+    ? { icons: { 16: "logo.png", 32: "logo.png", 48: "logo.png", 128: "logo.png" } }
+    : {}),
+  background: { service_worker: "background.js", type: "module" },
+  web_accessible_resources: [{ resources: ["index.js"], matches }],
+  content_scripts: [
+    { matches, js: ["contentScript.js"], run_at: "document_start", all_frames: false },
+  ],
+};
+
+// Strip CSP + frame guards on the target, and allow the target to pull from
+// localhost and the SDK host.
+const rules = [
+  {
+    id: 1,
+    priority: 1,
+    action: {
+      type: "modifyHeaders",
+      responseHeaders: [
+        { operation: "remove", header: "content-security-policy" },
+        { operation: "remove", header: "content-security-policy-report-only" },
+        { operation: "remove", header: "x-frame-options" },
+      ],
+    },
+    condition: {
+      requestDomains,
+      resourceTypes: [
+        "main_frame", "sub_frame", "stylesheet", "script", "xmlhttprequest",
+        "font", "object", "image", "media", "websocket", "other",
+      ],
+    },
+  },
+  {
+    id: 2,
+    priority: 1,
+    action: {
+      type: "modifyHeaders",
+      responseHeaders: [
+        { operation: "set", header: "access-control-allow-origin", value: new URL(startUrl).origin },
+        { operation: "set", header: "access-control-allow-methods", value: "GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH" },
+        { operation: "set", header: "access-control-allow-headers", value: "*" },
+        { operation: "set", header: "access-control-allow-credentials", value: "true" },
+      ],
+    },
+    condition: {
+      requestDomains: ["localhost", scriptHost],
+      initiatorDomains: requestDomains,
+      resourceTypes: ["script", "xmlhttprequest", "stylesheet", "font", "image", "media", "websocket", "other"],
+    },
+  },
+];
+
+const indexJs = `// GENERATED by scripts/inject.mjs — do not edit. Target: ${target.name}
+const LOAD_LOCALLY = ${target.loadLocally};
+const SDK_URL = ${JSON.stringify(sdkUrl)};
+const LOCAL_ACTIONS_URL = ${JSON.stringify(localActionsUrl)};
+const NAMESPACE = "foldspace";
+const PRODUCT_ID = ${JSON.stringify(target.productId)};
+const AGENT_API_NAME = ${JSON.stringify(target.agentApiName)};
+const REMOTE_ACTIONS_ENV = ${JSON.stringify(target.remoteActionsEnv)};
+const MODE = ${JSON.stringify(target.mode)};
+const OVERRIDE_KEY = ${JSON.stringify(target.overrideKey)};
+
+function attachActions() {
+  const actions = window.__FOLDSPACE_REMOTE_ACTIONS__;
+  const agent = window.__FOLDSPACE_AGENT__;
+  if (!actions || !agent) {
+    console.error("[foldspace-dev] actions or agent missing");
+    return;
+  }
+  delete window.__FOLDSPACE_REMOTE_ACTIONS__;
+  agent.addActionHandlers(actions);
+  console.log("[foldspace-dev] actions attached:", Object.keys(actions).length);
+}
+
+function loadRemoteActionsLocally() {
+  const script = document.createElement("script");
+  script.type = "text/javascript";
+  script.async = true;
+  script.src = LOCAL_ACTIONS_URL + "?t=" + Date.now();
+  script.onload = attachActions;
+  script.onerror = () => {
+    // Direct fetch blocked — fall back to the service worker.
+    window.addEventListener(
+      "message",
+      (event) => {
+        if (event.data.type === "INJECT_FOLDSPACE_REMOTE_ACTIONS_RESPONSE" && event.data.ok) {
+          attachActions();
+        }
+      },
+      { once: true }
+    );
+    window.postMessage({ type: "INJECT_FOLDSPACE_REMOTE_ACTIONS", src: LOCAL_ACTIONS_URL }, "*");
+    console.warn("[foldspace-dev] direct load failed, using background fetch. Is 'npm run dev' running?");
+  };
+  document.head.appendChild(script);
+}
+
+// The real SDK has loaded when it has replaced the stub with its own methods.
+// The stub only ever has q and k.
+function sdkLoaded() {
+  return typeof window[NAMESPACE] === "function" && typeof window[NAMESPACE].agent === "function";
+}
+
+function appendSdkScript() {
+  const w = window, d = document, n = NAMESPACE;
+  const k = OVERRIDE_KEY || ("EU-" + PRODUCT_ID + "-1-1");
+  w[n] = w[n] || function () { (w[n].q = w[n].q || []).push(arguments); };
+  w.__FOLD_SPACE__ = n;
+  w[n].k = k;
+  if (d.querySelector("script[data-foldspace-sdk]")) return;
+  // Wait for a real body. The SDK mounts its widget container on load, and
+  // appendChild into a null body throws inside eucera.js — the widget then
+  // never renders even though the SDK "loaded". Throwing here is deliberate:
+  // the retry loop keeps trying until the document is ready for it.
+  if (!d.body) throw new Error("document.body not ready");
+  const s = d.createElement("script");
+  s.async = true;
+  s.src = SDK_URL + "?k=" + k;
+  s.setAttribute("data-foldspace-sdk", "1");
+  const h = d.getElementsByTagName("script")[0];
+  if (h && h.parentNode) h.parentNode.insertBefore(s, h);
+  else (d.head || d.documentElement).appendChild(s);
+}
+
+function initFoldspaceSDK() {
+  // At document-start there may be no head and no documentElement yet, so the
+  // first append can throw. Schedule the retry BEFORE trying, or a throw here
+  // leaves the stub on window with nothing ever loading the real SDK — which
+  // looks identical to a working page until you ask for the agent.
+  let tries = 0;
+  const retry = setInterval(() => {
+    if (sdkLoaded() || ++tries > 60) { clearInterval(retry); return; }
+    tryAppendSdkScript();
+  }, 250);
+  document.addEventListener("DOMContentLoaded", tryAppendSdkScript);
+  tryAppendSdkScript();
+}
+
+function tryAppendSdkScript() {
+  try { appendSdkScript(); } catch (e) { /* DOM not ready yet; the retry covers it */ }
+}
+
+function init() {
+  const win = window;
+  win.foldspace("when", "ready", async () => {
+    const configuration = { enableDebugLogs: true };
+
+    if (MODE === "EMBEDDED") {
+      const container = document.createElement("div");
+      container.id = "foldspace-container";
+      document.body.appendChild(container);
+      configuration.embeddedConfiguration = { container };
+    }
+
+    if (!LOAD_LOCALLY) {
+      configuration.remoteActionsSettings = { enabled: true, environment: REMOTE_ACTIONS_ENV };
+      console.log("[foldspace-dev] remote actions (" + REMOTE_ACTIONS_ENV + ")");
+    } else {
+      console.log("[foldspace-dev] local actions from " + LOCAL_ACTIONS_URL);
+    }
+
+    const agent = win.foldspace.agent({ apiName: AGENT_API_NAME, mode: MODE, configuration });
+    win.__FOLDSPACE_AGENT__ = agent;
+
+    agent.on("*", (e) => {
+      if (e.eventName === "agent.ready" && LOAD_LOCALLY) {
+        // attach.mjs injects the bundle at document-start, so the global is
+        // usually already here — no network, no dev server, and it works
+        // against a browser that cannot reach this machine at all.
+        if (window.__FOLDSPACE_REMOTE_ACTIONS__) attachActions();
+        else loadRemoteActionsLocally();
+      }
+    });
+
+    // Ctrl+Shift+R reloads local actions without a page refresh.
+    window.addEventListener("keydown", (e) => {
+      if (e.ctrlKey && e.shiftKey && e.key.toLowerCase() === "r" && LOAD_LOCALLY) {
+        e.preventDefault();
+        console.log("[foldspace-dev] reloading actions...");
+        loadRemoteActionsLocally();
+      }
+    });
+  });
+}
+
+if (window.top !== window.self) {
+  // Third-party iframes (Zendesk, Chameleon, ...) must not run this.
+} else {
+  // Guard on the loaded SDK, not on the stub: window.foldspace being truthy
+  // only means some copy of this script got as far as defining the queue.
+  if (!sdkLoaded()) initFoldspaceSDK();
+  init();
+}
+function addDevBadge() {
+  if (document.getElementById("foldspace-dev-badge")) return;
+  const b = document.createElement("div");
+  b.id = "foldspace-dev-badge";
+  b.textContent = "FOLDSPACE DEV \u00b7 " + AGENT_API_NAME;
+  b.style.cssText = [
+    "position:fixed", "top:0", "left:0", "z-index:2147483647",
+    "background:#3247F2", "color:#fff",
+    "font:700 10px/1 ui-monospace,SFMono-Regular,Menlo,monospace",
+    "letter-spacing:.12em", "padding:5px 10px",
+    "border-bottom-right-radius:4px", "pointer-events:none",
+    "box-shadow:0 1px 6px rgba(0,0,0,.35)",
+  ].join(";");
+  (document.body || document.documentElement).appendChild(b);
+}
+if (window.top === window.self) {
+  // The host app is a SPA and will re-render over us, so keep re-asserting.
+  const keepBadge = () => { if (document.body) addDevBadge(); };
+  keepBadge();
+  document.addEventListener("DOMContentLoaded", keepBadge);
+  setInterval(keepBadge, 2000);
+}
+
+console.log("[foldspace-dev] injected", { agent: AGENT_API_NAME, product: PRODUCT_ID, mode: MODE });
+`;
+
+fs.writeFileSync(path.join(extDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+fs.writeFileSync(path.join(extDir, "csp_rules.json"), JSON.stringify(rules, null, 2));
+fs.writeFileSync(path.join(extDir, "index.js"), indexJs);
+for (const f of ["contentScript.js", "background.js"]) {
+  fs.copyFileSync(path.join(root, "extension", f), path.join(extDir, f));
+}
+const logoSrc = path.join(root, "extension", "logo.png");
+if (fs.existsSync(logoSrc)) fs.copyFileSync(logoSrc, path.join(extDir, "logo.png"));
+
+console.log(`Generated ${path.relative(root, extDir)}/`);
+console.log(`  target   ${target.name}`);
+console.log(`  agent    ${target.agentApiName}  (product ${target.productId})`);
+console.log(`  hosts    ${target.hosts.join(", ")}`);
+console.log(`  actions  ${target.loadLocally ? localActionsUrl : "remote " + target.remoteActionsEnv}`);
+console.log(`  url      ${startUrl}`);
+
+if (args.flags.has("print")) process.exit(0);
+
+// ---------------------------------------------------------------- launch
+
+function findChrome() {
+  const candidates =
+    os.platform() === "darwin"
+      ? [
+          "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+          "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+          "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]
+      : ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium"];
+  return candidates.find((p) => fs.existsSync(p));
+}
+
+const chrome = process.env.CHROME_PATH || findChrome();
+if (!chrome) {
+  console.error("\nChrome not found. Set CHROME_PATH=/path/to/chrome and retry.");
+  process.exit(1);
+}
+
+fs.mkdirSync(profileDir, { recursive: true });
+
+const debugPort = args.port || "9222";
+
+// Record it so attach does not have to be told again. inject and attach
+// disagreeing about the port is how you end up attached to a different
+// browser than the one you launched.
+fs.mkdirSync(workDir, { recursive: true });
+fs.writeFileSync(
+  path.join(workDir, "state.json"),
+  JSON.stringify({ debugPort, target: targetName }, null, 2),
+);
+
+// Name the profile so this window is identifiable among other Chrome windows.
+function nameProfile() {
+  const writeMerged = (file, mutate) => {
+    let data = {};
+    try { data = JSON.parse(fs.readFileSync(file, "utf8")); } catch {}
+    mutate(data);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data));
+  };
+  const label = `Foldspace Dev \u2014 ${target.name}`;
+  writeMerged(path.join(profileDir, "Local State"), (d) => {
+    d.profile = d.profile || {};
+    d.profile.info_cache = d.profile.info_cache || {};
+    d.profile.info_cache.Default = {
+      ...(d.profile.info_cache.Default || {}),
+      name: label,
+      is_using_default_name: false,
+      avatar_icon: "chrome://theme/IDR_PROFILE_AVATAR_26",
+      is_using_default_avatar: false,
+    };
+    d.profile.last_used = "Default";
+  });
+  writeMerged(path.join(profileDir, "Default", "Preferences"), (d) => {
+    d.profile = d.profile || {};
+    d.profile.name = label;
+  });
+}
+nameProfile();
+
+const chromeArgs = [
+  `--user-data-dir=${profileDir}`,
+  `--remote-debugging-port=${debugPort}`,
+  // The dev extension plus a theme-only extension that paints the browser
+  // Foldspace blue — so this window is never mistaken for your own Chrome.
+  `--load-extension=${extDir},${themeDir}`,
+  `--disable-extensions-except=${extDir},${themeDir}`,
+  // Chrome 136+ dropped --load-extension. Keep the legacy switch for older
+  // builds, and enable the CDP Extensions domain so we can load it at runtime.
+  "--disable-features=DisableLoadExtensionCommandLineSwitch",
+  "--enable-unsafe-extension-debugging",
+  "--no-first-run",
+  "--no-default-browser-check",
+  "--test-type",
+  startUrl,
+];
+
+console.log(`\nLaunching Chrome \u2014 profile ${path.relative(root, profileDir)}, devtools on :${debugPort}.`);
+console.log("Log in to the app once — the profile persists between runs.\n");
+
+const child = spawn(chrome, chromeArgs, { detached: true, stdio: "ignore" });
+child.unref();
+
+// --- theme -------------------------------------------------------------
+//
+// Chrome 151 ignores --load-extension entirely: launching with it produces a
+// profile with ZERO installed extensions. That is also why the generated dev
+// extension has never actually loaded — its content script, service worker and
+// CSP rules have all been inert. Verified 2026-08-25 by reading
+// Default/Preferences after launch.
+//
+// The CDP Extensions domain still works (that is what
+// --enable-unsafe-extension-debugging is for), so load the theme that way.
+// Only the theme: the SDK and actions arrive over CDP from attach.mjs, and the
+// dev extension is not required for them.
+async function loadTheme() {
+  const endpoint = `http://127.0.0.1:${debugPort}/json/version`;
+  for (let i = 0; i < 40; i++) {
+    try {
+      const version = await (await fetch(endpoint)).json();
+      const ws = new WebSocket(version.webSocketDebuggerUrl);
+      await new Promise((resolve, reject) => {
+        ws.addEventListener("open", resolve);
+        ws.addEventListener("error", reject);
+      });
+      const done = new Promise((resolve) => {
+        ws.addEventListener("message", (event) => {
+          const message = JSON.parse(event.data);
+          if (message.id === 1) resolve(message);
+        });
+      });
+      ws.send(JSON.stringify({ id: 1, method: "Extensions.loadUnpacked", params: { path: themeDir } }));
+      const result = await done;
+      ws.close();
+      if (result.error) console.log(`  theme not applied: ${result.error.message}`);
+      return;
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+  }
+  console.log("  theme not applied: Chrome did not expose CDP in time");
+}
+
+await loadTheme();

package/bin/packageExtension.mjs

@@ -0,0 +1,29 @@
+import { execFileSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
+const projectName = path.basename(projectDir);
+const extensionDir = path.join(projectDir, "extension");
+const zipPath = path.join(projectDir, `${projectName}-extension.zip`);
+
+if (!fs.existsSync(extensionDir)) {
+  console.error("packageExtension: extension/ directory not found");
+  process.exit(1);
+}
+
+try {
+  if (fs.existsSync(zipPath)) {
+    fs.rmSync(zipPath);
+  }
+  execFileSync("zip", ["-r", zipPath, "."], {
+    cwd: extensionDir,
+    stdio: "inherit",
+  });
+  console.log(`packageExtension: created ${zipPath}`);
+} catch {
+  console.error("packageExtension: failed to create extension.zip");
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@foldspace_npm/harness",
+  "version": "0.1.0",
+  "description": "Build, inject and verify Foldspace agent experiences against a live app.",
+  "type": "module",
+  "bin": {
+    "foldspace": "bin/cli.mjs",
+    "foldspace-build": "bin/build-cli.mjs",
+    "foldspace-inject": "bin/inject.mjs",
+    "foldspace-attach": "bin/attach.mjs",
+    "foldspace-deploy": "bin/deploy.mjs",
+    "foldspace-package-extension": "bin/packageExtension.mjs"
+  },
+  "files": ["bin", "src", "templates", "README.md"],
+  "dependencies": {
+    "esbuild": "^0.20.0",
+    "tsx": "^4.7.0"
+  },
+  "engines": { "node": ">=20" },
+  "publishConfig": {
+    "access": "public"
+  }
+}