@foldspace_npm/harness 0.1.2 → 0.1.4

package/bin/inject.mjs

@@ -2,28 +2,24 @@
 /**
  * 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/.
+ * Launches an isolated Chrome profile for local CDP verification. Action
+ * loading and SDK bootstrap are owned by attach.mjs; inject does not generate
+ * or load an application 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
+ *   npm run inject -- --print                       # resolve target 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");
 
@@ -31,16 +27,37 @@ const profileDir = path.join(workDir, "chrome-profile");
 
 function parseArgs(argv) {
   const out = { flags: new Set() };
+  const valueOptions = new Set([
+    "--target",
+    "--url",
+    "--product",
+    "--agent",
+    "--hosts",
+    "--key",
+    "--port",
+  ]);
   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");
+    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];
+    else if (valueOptions.has(a)) {
+      if (!argv[i + 1] || argv[i + 1].startsWith("--")) {
+        throw new Error(`${a} requires a value`);
+      }
+      out[a.slice(2)] = argv[++i];
+    } else {
+      throw new Error(`unknown option '${a}'`);
+    }
   }
   return out;
 }
-const args = parseArgs(process.argv.slice(2));
+let args;
+try {
+  args = parseArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(`inject: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
 
 // ---------------------------------------------------------------- config
 
@@ -62,13 +79,12 @@ if (!args.url && !base.startUrl) {
 
 const startUrl = args.url || base.startUrl;
 
-// Derive host patterns from the URL when not configured — registrable domain + wildcard.
+// Without explicit hosts, fail closed to the exact launch hostname. Expanding
+// registrable domains correctly requires public-suffix data.
 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}`];
+  return [hostname];
 }
 
 // A --url with no --target means we are pointing at an app the config does not
@@ -88,9 +104,7 @@ const target = {
   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"]) {
@@ -100,21 +114,24 @@ for (const required of ["productId", "agentApiName"]) {
   }
 }
 
-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;
+console.log(`Resolved Foldspace target:`);
+console.log(`  target   ${target.name}`);
+console.log(`  agent    ${target.agentApiName}  (product ${target.productId})`);
+console.log(`  hosts    ${target.hosts.join(", ")}`);
+console.log(`  url      ${startUrl}`);
 
-// ---------------------------------------------------------------- generate
+if (args.flags.has("print")) process.exit(0);
+
+// ---------------------------------------------------------------- launch
 
-fs.rmSync(extDir, { recursive: true, force: true });
-fs.mkdirSync(extDir, { recursive: true });
+// Remove the obsolete generated application extension from older harness runs.
+fs.rmSync(path.join(workDir, "extension"), {
+  recursive: true,
+  force: 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.
+// .foldspace-dev`. It is cosmetic and never loads Foldspace or action code.
 fs.rmSync(themeDir, { recursive: true, force: true });
 fs.mkdirSync(themeDir, { recursive: true });
 fs.writeFileSync(
@@ -142,262 +159,6 @@ fs.writeFileSync(
   }, 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"
@@ -426,7 +187,18 @@ const debugPort = args.port || "9222";
 fs.mkdirSync(workDir, { recursive: true });
 fs.writeFileSync(
   path.join(workDir, "state.json"),
-  JSON.stringify({ debugPort, target: targetName }, null, 2),
+  JSON.stringify(
+    {
+      debugPort,
+      target: targetName,
+      resolvedTarget: {
+        ...target,
+        sdkUrl: cfg.sdkUrl,
+      },
+    },
+    null,
+    2,
+  ),
 );
 
 // Name the profile so this window is identifiable among other Chrome windows.
@@ -461,10 +233,10 @@ 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}`,
+  // The theme only paints the isolated window Foldspace blue. SDK and action
+  // code are loaded later by attach over CDP.
+  `--load-extension=${themeDir}`,
+  `--disable-extensions-except=${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",
@@ -483,11 +255,8 @@ 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.
+// Chrome 151 ignores --load-extension, so load the optional cosmetic theme
+// through CDP. No application extension is generated or loaded.
 //
 // The CDP Extensions domain still works (that is what
 // --enable-unsafe-extension-debugging is for), so load the theme that way.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.2",
-  "description": "Build, inject and verify Foldspace agent experiences against a live app.",
+  "version": "0.1.4",
+  "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
     "foldspace": "bin/cli.mjs",
     "harness": "bin/cli.mjs"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "files": [
     "bin",
     "src",