@foldspace_npm/harness 0.1.0

package/src/init.mjs

@@ -0,0 +1,301 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const defaultTemplateRoot = path.join(packageRoot, "templates", "agent-starter");
+const allowedFlags = new Set(["name", "product-id", "agent-api-name", "domain"]);
+const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
+
+export const initUsage =
+  "foldspace init <directory> --product-id <id> --agent-api-name <name> --domain <host> [--name <display-name>]";
+
+function assertSupportedNode() {
+  const major = Number.parseInt(process.versions.node.split(".", 1)[0], 10);
+  if (!Number.isInteger(major) || major < 20) {
+    throw new Error(`Node 20 or newer is required; found ${process.versions.node}.`);
+  }
+}
+
+function readFlag(argv, index) {
+  const argument = argv[index];
+  const equalsIndex = argument.indexOf("=");
+  const name = argument.slice(2, equalsIndex === -1 ? undefined : equalsIndex);
+
+  if (!allowedFlags.has(name)) {
+    throw new Error(`Unknown option: --${name}`);
+  }
+
+  if (equalsIndex !== -1) {
+    const value = argument.slice(equalsIndex + 1);
+    if (!value) {
+      throw new Error(`Missing value for --${name}`);
+    }
+    return { name, value, consumed: 1 };
+  }
+
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for --${name}`);
+  }
+  return { name, value, consumed: 2 };
+}
+
+export function parseInitArgs(argv) {
+  const positional = [];
+  const flags = {};
+
+  for (let index = 0; index < argv.length; ) {
+    const argument = argv[index];
+    if (argument.startsWith("--")) {
+      const parsed = readFlag(argv, index);
+      if (flags[parsed.name] !== undefined) {
+        throw new Error(`Option provided more than once: --${parsed.name}`);
+      }
+      flags[parsed.name] = parsed.value;
+      index += parsed.consumed;
+      continue;
+    }
+
+    positional.push(argument);
+    index += 1;
+  }
+
+  if (positional.length !== 1) {
+    throw new Error(`Usage: ${initUsage}`);
+  }
+
+  for (const required of ["product-id", "agent-api-name", "domain"]) {
+    if (!flags[required]) {
+      throw new Error(`Missing required option: --${required}\nUsage: ${initUsage}`);
+    }
+  }
+
+  return {
+    targetDir: path.resolve(positional[0]),
+    displayName: flags.name || path.basename(path.resolve(positional[0])),
+    productId: flags["product-id"],
+    agentApiName: flags["agent-api-name"],
+    domain: flags.domain,
+  };
+}
+
+function toPackageName(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function validateIdentifier(value, label) {
+  const normalized = value.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(normalized)) {
+    throw new Error(
+      `${label} must start with a letter or number and contain only letters, numbers, hyphens, or underscores.`,
+    );
+  }
+  return normalized;
+}
+
+function validateProductId(value) {
+  const productId = validateIdentifier(value, "Product ID");
+  if (/^EU-/i.test(productId)) {
+    throw new Error("Product ID must be the bare product ID, not an EU-… SDK key.");
+  }
+  return productId;
+}
+
+function normalizeTarget(value) {
+  const raw = value.trim();
+  if (!raw || raw.includes("*")) {
+    throw new Error("Domain must be a concrete hostname without a wildcard.");
+  }
+
+  let url;
+  try {
+    url = new URL(raw.includes("://") ? raw : `https://${raw}`);
+  } catch {
+    throw new Error(`Invalid domain: ${value}`);
+  }
+
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    url.port ||
+    (url.pathname !== "/" && url.pathname !== "") ||
+    url.search ||
+    url.hash
+  ) {
+    throw new Error("Domain must contain only an HTTP(S) hostname, without credentials, a port, path, query, or fragment.");
+  }
+
+  const domain = url.hostname.toLowerCase().replace(/\.$/, "");
+  if (!domain || domain.includes("..")) {
+    throw new Error(`Invalid domain: ${value}`);
+  }
+
+  return {
+    domain,
+    startUrl: `${url.protocol}//${domain}/`,
+  };
+}
+
+function readHarnessVersion(root) {
+  const manifestPath = path.join(root, "package.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (typeof manifest.version !== "string" || !manifest.version) {
+    throw new Error(`Harness package version is missing from ${manifestPath}`);
+  }
+  return manifest.version;
+}
+
+function createTemplateValues(config, harnessVersion) {
+  const displayName = config.displayName.trim();
+  if (!displayName || /[\r\n]/.test(displayName) || displayName.includes("{{")) {
+    throw new Error("Display name must be a non-empty single line and cannot contain '{{'.");
+  }
+
+  const packageName = toPackageName(displayName);
+  if (!packageName) {
+    throw new Error("Display name must contain at least one letter or number.");
+  }
+
+  const productId = validateProductId(config.productId);
+  const agentApiName = validateIdentifier(config.agentApiName, "Agent API name");
+  const target = normalizeTarget(config.domain);
+  const hosts =
+    target.domain === "localhost" || /^\d+(?:\.\d+){3}$/.test(target.domain)
+      ? [target.domain]
+      : [target.domain, `*.${target.domain}`];
+
+  return {
+    DISPLAY_NAME: displayName,
+    PACKAGE_NAME: packageName,
+    PACKAGE_DESCRIPTION_JSON: JSON.stringify(`Foldspace browser actions for ${displayName}.`),
+    PRODUCT_ID_JSON: JSON.stringify(productId),
+    AGENT_API_NAME_JSON: JSON.stringify(agentApiName),
+    APP_DOMAIN_JSON: JSON.stringify(target.domain),
+    START_URL_JSON: JSON.stringify(target.startUrl),
+    HOSTS_JSON: JSON.stringify(hosts),
+    HARNESS_VERSION: harnessVersion,
+  };
+}
+
+function renderTemplate(content, values, sourcePath) {
+  const rendered = content.replace(tokenPattern, (_match, key) => {
+    if (!(key in values)) {
+      throw new Error(`Missing value for {{${key}}} in ${sourcePath}`);
+    }
+    return values[key];
+  });
+
+  const unresolved = rendered.match(tokenPattern);
+  if (unresolved) {
+    throw new Error(`Unresolved template token ${unresolved[0]} in ${sourcePath}`);
+  }
+  return rendered;
+}
+
+function assertInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Template path escapes the project root: ${candidate}`);
+  }
+}
+
+function copyTemplate(templateRoot, targetRoot, values) {
+  const walk = (relativeDir) => {
+    const sourceDir = path.join(templateRoot, relativeDir);
+    for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const relativePath = path.join(relativeDir, entry.name);
+      const sourcePath = path.join(templateRoot, relativePath);
+      // npm excludes .gitignore files from package tarballs, so the bundled
+      // template uses a publish-safe name and restores it during generation.
+      const outputPath = relativePath === "gitignore" ? ".gitignore" : relativePath;
+      const targetPath = path.join(targetRoot, outputPath);
+      assertInside(targetRoot, targetPath);
+
+      if (entry.isSymbolicLink()) {
+        throw new Error(`Template symlinks are not supported: ${sourcePath}`);
+      }
+      if (entry.isDirectory()) {
+        fs.mkdirSync(targetPath, { recursive: true });
+        walk(relativePath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        throw new Error(`Unsupported template entry: ${sourcePath}`);
+      }
+
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      const content = fs.readFileSync(sourcePath, "utf8");
+      fs.writeFileSync(targetPath, renderTemplate(content, values, sourcePath), "utf8");
+    }
+  };
+
+  walk("");
+}
+
+function validateGeneratedProject(projectDir) {
+  for (const relativePath of ["package.json", "foldspace.dev.json"]) {
+    const filePath = path.join(projectDir, relativePath);
+    JSON.parse(fs.readFileSync(filePath, "utf8"));
+  }
+}
+
+export function scaffoldProject(config, options = {}) {
+  const targetDir = config.targetDir;
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Refusing to overwrite existing path: ${targetDir}`);
+  }
+
+  const templateRoot = options.templateRoot || defaultTemplateRoot;
+  if (!fs.existsSync(templateRoot)) {
+    throw new Error(`Bundled project template not found: ${templateRoot}`);
+  }
+
+  const harnessVersion = options.harnessVersion || readHarnessVersion(options.packageRoot || packageRoot);
+  const values = createTemplateValues(config, harnessVersion);
+  const parentDir = path.dirname(targetDir);
+  fs.mkdirSync(parentDir, { recursive: true });
+  const temporaryDir = fs.mkdtempSync(path.join(parentDir, `.${path.basename(targetDir)}.foldspace-init-`));
+
+  try {
+    copyTemplate(templateRoot, temporaryDir, values);
+    validateGeneratedProject(temporaryDir);
+    if (fs.existsSync(targetDir)) {
+      throw new Error(`Target path appeared while initializing: ${targetDir}`);
+    }
+    fs.renameSync(temporaryDir, targetDir);
+  } catch (error) {
+    fs.rmSync(temporaryDir, { recursive: true, force: true });
+    throw error;
+  }
+
+  return {
+    targetDir,
+    packageName: values.PACKAGE_NAME,
+    harnessVersion,
+  };
+}
+
+export function runInit(argv, options = {}) {
+  assertSupportedNode();
+  const config = parseInitArgs(argv);
+  const result = scaffoldProject(config, options);
+  const log = options.log || console.log;
+
+  log(`Created Foldspace project at ${result.targetDir}`);
+  log(`Using @foldspace_npm/harness ${result.harnessVersion}`);
+  log("");
+  log("Next steps:");
+  log(`  cd ${result.targetDir}`);
+  log("  npm install --ignore-scripts");
+  log("  npm run build");
+  log("  npm run inject");
+  log("  npm run attach");
+
+  return result;
+}

package/src/transports/README.md

@@ -0,0 +1,24 @@
+# Transports
+
+The harness does the same three jobs regardless of where the browser is:
+
+    put the bundle in the page  ·  run code in the page  ·  look at the result
+
+Track A (`local`) does them over CDP against a browser on this machine.
+Track B (`extension`) will do them over a websocket to a Web Store extension in
+the user's own Chrome.
+
+`agent/`, `fixtures/` and the build are identical in both — only this layer
+differs. Keep it that way: "export to repo" from a hosted build is a copy only
+while the two tracks share an identical `agent/` directory.
+
+| Verb | local (CDP) | extension (planned) |
+|---|---|---|
+| `loadBundle` | `addScriptToEvaluateOnNewDocument` / `Fetch.fulfillRequest` | `<script src>` at the deployed CDN path |
+| `evaluate` | `Runtime.evaluate` | content-script message |
+| `screenshot` | `Page.captureScreenshot` | `tabs.captureVisibleTab` |
+| `relaxCSP` | `Page.setBypassCSP` | `declarativeNetRequest` header rules |
+| `navigate` | `Page.navigate` | `tabs.update` |
+
+`local` is implemented today as `bin/inject.mjs` + `bin/attach.mjs`.
+`extension` is not built; see `architecture-hosted.md`.

package/templates/agent-starter/CLAUDE.md

@@ -0,0 +1,90 @@
+# Foldspace browser actions
+
+## Scope
+
+This project contains Foldspace action handlers. The customer website, SDK
+snippet, `identify()` call, and layout are out of scope unless the user asks for
+changes there.
+
+## Before building
+
+1. Connect Product MCP and verify that `list_agents` works.
+2. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
+   `list_task_agents`.
+3. Use `discover_actions` to identify candidate experiences, then let the user
+   choose what to build.
+
+## Build workflow
+
+An experience can require several reusable actions. Separate lookup actions
+from actions that read or mutate a selected resource.
+
+1. Agree on the experience and how its actions compose.
+2. Create the action metadata as a draft.
+3. Ask before publishing when the agent has real users; publishing is a live
+   product change.
+4. Observe the real target workflow and capture its browser requests.
+5. Generate the typed handler skeleton from the published action schema.
+6. Implement the handler using the observed request and response shapes.
+7. Register the handler in `agent/actions/index.ts`.
+8. Complete the verification gates below.
+
+## API rules
+
+Actions execute in the user's signed-in browser session.
+
+- Use the same internal APIs as the product page, with
+  `credentials: "include"`.
+- Never guess endpoints or schemas. Capture at least one real request and
+  response before implementing a parser.
+- Verify that the user is signed in before observing a workflow.
+- Do not substitute a public developer API when the browser session is missing;
+  ask the user to sign in.
+- Validate parameters and return sanitized errors.
+
+## Local harness loop
+
+```bash
+npm run dev
+npm run inject
+npm run attach
+```
+
+`inject` launches an isolated Chrome profile and records its debug port.
+`attach` loads the SDK and the local `dist/index.js` bundle. Use
+`npm run attach -- --bootstrap` when the target page does not already embed the
+Foldspace SDK.
+
+The attach log must report `actions attached: N` before treating the page as
+running local action code.
+
+## Verification gates
+
+Do not report success without all six:
+
+1. TypeScript compiles with `npx tsc --noEmit -p tsconfig.json`.
+2. The expected handler appears in `dist/index.js`.
+3. The browser reports the expected number of attached actions.
+4. The action behaves correctly against the real target workflow.
+5. Existing neighbouring action fixtures still pass when fixtures exist.
+6. Browser evidence came from the live target, not from hand-authored examples.
+
+## Layout
+
+- `agent/actions/` — one handler per action, registered in `index.ts`
+- `agent/api/` — one HTTP helper per endpoint
+- `agent/constants.ts` — agent, product, and domain identifiers
+- `agent/utils.ts` — Foldspace agent lookup
+- `foldspace.dev.json` — local harness target configuration
+
+Do not introduce another bundler or bundle format.
+
+## Safety
+
+- Do not commit secrets, cookies, HAR files, browser storage, or
+  `.foldspace-dev/`.
+- Local handler changes are not cloud publication.
+- Creating or publishing Foldspace resources requires explicit approval.
+- Action keys and parameter names must match the published schema.
+- Search Foldspace documentation before asserting unfamiliar platform
+  behaviour.

package/templates/agent-starter/README.md

@@ -0,0 +1,54 @@
+# {{DISPLAY_NAME}}
+
+This project contains Foldspace browser action handlers. The handlers are built
+locally and loaded into the configured product page by `@foldspace_npm/harness`.
+The customer website and its Foldspace SDK installation are separate.
+
+## Setup
+
+`foldspace init` generated the product, agent, and domain settings in:
+
+- `agent/constants.ts`
+- `foldspace.dev.json`
+
+Install dependencies without running dependency lifecycle scripts, then build:
+
+```bash
+npm install --ignore-scripts
+npm run build
+```
+
+## Project layout
+
+```text
+agent/
+  actions/     one file per action; register actions in index.ts
+  api/         one file per HTTP helper
+  constants.ts product, agent, and domain identifiers
+  utils.ts     Foldspace agent lookup
+foldspace.dev.json
+CLAUDE.md
+```
+
+## Commands
+
+```bash
+npm run build    # create dist/index.js
+npm run dev      # rebuild dist/index.js on changes
+npm run inject   # launch the dedicated Chrome profile
+npm run attach   # load the SDK and local actions over CDP
+```
+
+Run `inject` before `attach`. Sign in to the product in the Chrome window that
+`inject` opens. For a product that does not already embed the Foldspace SDK, run
+`npm run attach -- --bootstrap`.
+
+## Add an action
+
+1. Define and publish the action in Agent Studio or through Product MCP.
+2. Copy `agent/actions/_example.ts` to `agent/actions/<action_key>.ts`.
+3. Implement the handler from observed browser API evidence.
+4. Import and register the handler in `agent/actions/index.ts`.
+5. Type-check, rebuild, attach, and verify it in the target product.
+
+Action keys and parameter names must exactly match the published action schema.

package/templates/agent-starter/agent/actions/_example.ts

@@ -0,0 +1,18 @@
+// Copy this file to <action_key>.ts and register it in index.ts.
+// Do not register _example — it is not a real Agent Studio action.
+
+export const example_action = {
+  execute: async (params: { message?: string }) => {
+    const message = typeof params?.message === "string" ? params.message.trim() : "";
+    if (!message) {
+      return { ok: false, error: "message is required" };
+    }
+
+    try {
+      return { ok: true, echo: message };
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : "unknown error";
+      return { ok: false, error: detail };
+    }
+  },
+};

package/templates/agent-starter/agent/actions/index.ts

@@ -0,0 +1,10 @@
+// Entry point for the agent actions. One file per action in this directory.
+//
+// Registration here is the switch: the SDK transmits these to the server, and
+// the server excludes any active action it does not receive. Comment an entry
+// out and the copilot can no longer see it — no unpublishing required.
+
+const actions = {};
+(window as any).__FOLDSPACE_REMOTE_ACTIONS__ = actions;
+
+export default actions;

package/templates/agent-starter/agent/api/.gitkeep

@@ -0,0 +1 @@
+# API helpers belong in this directory.

package/templates/agent-starter/agent/constants.ts

@@ -0,0 +1,3 @@
+export const AGENT_API_NAME = {{AGENT_API_NAME_JSON}};
+export const PRODUCT_ID = {{PRODUCT_ID_JSON}};
+export const APP_DOMAIN = {{APP_DOMAIN_JSON}};

package/templates/agent-starter/agent/utils.ts

@@ -0,0 +1,15 @@
+import { AGENT_API_NAME } from "./constants";
+
+let agent: any | null = null;
+
+export function getAgent(): any | null {
+  if (agent) {
+    return agent;
+  }
+
+  agent = (window as any).foldspace?.agent({
+    apiName: AGENT_API_NAME,
+  });
+
+  return agent;
+}

package/templates/agent-starter/foldspace.dev.json

@@ -0,0 +1,17 @@
+{
+  "$comment": "Generated by foldspace init. Use the bare product ID, not the EU-… SDK key.",
+  "defaultTarget": "app",
+  "sdkUrl": "https://script.eucerahive.io/web/sdk/foldspace.js",
+  "localActionsUrl": "http://localhost:3007/dist/index.js",
+  "targets": {
+    "app": {
+      "name": "App",
+      "startUrl": {{START_URL_JSON}},
+      "productId": {{PRODUCT_ID_JSON}},
+      "agentApiName": {{AGENT_API_NAME_JSON}},
+      "hosts": {{HOSTS_JSON}},
+      "mode": "OVERLAY",
+      "loadLocally": true
+    }
+  }
+}

package/templates/agent-starter/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+.foldspace-dev/
+.DS_Store
+*.log
+*.zip

package/templates/agent-starter/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "1.0.0",
+  "description": {{PACKAGE_DESCRIPTION_JSON}},
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "foldspace-build --watch",
+    "build": "foldspace-build",
+    "inject": "foldspace-inject",
+    "attach": "foldspace-attach"
+  },
+  "devDependencies": {
+    "@foldspace_npm/harness": "{{HARNESS_VERSION}}",
+    "typescript": "^5.3.3"
+  }
+}

package/templates/agent-starter/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": false,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}