@foldspace_npm/harness 0.1.1 → 0.1.3

package/templates/agent-starter/README.md

@@ -26,22 +26,45 @@ agent/
   api/         one file per HTTP helper
   constants.ts product, agent, and domain identifiers
   utils.ts     Foldspace agent lookup
+docs/          optional notes for coding-agent learnings (create when needed)
 foldspace.dev.json
 CLAUDE.md
 ```
 
+## Agent learnings
+
+Coding agents may keep durable, repository-specific lessons under `docs/` so
+later sessions do not repeat the same mistakes. Create the folder when the first
+note is useful; do not commit an empty `docs/` directory.
+
+Good notes cover verified gotchas, failed approaches, design rationale, and
+useful verification commands. Keep them concise and evidence-based. Before
+similar work, read any relevant notes in `docs/`. Do not store secrets, cookies,
+HAR files, browser storage, or other transient session data there.
+
 ## Commands
 
 ```bash
+npx foldspace help # discover commands, risks, and next steps
 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
+npm run attach   # load local actions and observe the agent 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`.
+`inject` opens. `inject` does not generate an application extension; `attach`
+loads `dist/index.js` directly through CDP.
+
+Choose the attach mode from the state of the target page:
+
+- Default swap: the page already has the configured product and agent.
+- `npm run attach -- --bootstrap`: the page has no Foldspace SDK.
+- `npm run attach -- --replace`: the page has a different product or agent, or
+  an SDK without the configured agent.
+
+Run `npx foldspace help attach` for full requirements and safety options. Coding
+agents can read the versioned contract with `npx foldspace help --json`.
 
 ## Add an action
 

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

@@ -2,7 +2,6 @@
   "$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",
@@ -10,8 +9,7 @@
       "productId": {{PRODUCT_ID_JSON}},
       "agentApiName": {{AGENT_API_NAME_JSON}},
       "hosts": {{HOSTS_JSON}},
-      "mode": "OVERLAY",
-      "loadLocally": true
+      "mode": "OVERLAY"
     }
   }
 }

package/templates/agent-starter/package.json

@@ -5,10 +5,10 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "foldspace-build --watch",
-    "build": "foldspace-build",
-    "inject": "foldspace-inject",
-    "attach": "foldspace-attach"
+    "dev": "foldspace build --watch",
+    "build": "foldspace build",
+    "inject": "foldspace inject",
+    "attach": "foldspace attach"
   },
   "devDependencies": {
     "@foldspace_npm/harness": "{{HARNESS_VERSION}}",

package/bin/buildExtension.mjs

@@ -1,90 +0,0 @@
-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 indexPath = path.join(projectDir, "extension", "index.js");
-
-const LOAD_LOCALLY_TRUE = "const LOAD_LOCALLY = true;";
-const LOAD_LOCALLY_FALSE = "const LOAD_LOCALLY = false;";
-const REMOTE_ENV_DEV = 'const REMOTE_ACTIONS_ENV = "DEV";';
-const REMOTE_ENV_PROD = 'const REMOTE_ACTIONS_ENV = "PROD";';
-
-function parseArgs(argv) {
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--env" && argv[i + 1]) return argv[++i];
-  }
-  return null;
-}
-
-const env = parseArgs(process.argv.slice(2));
-if (!env || (env !== "dev" && env !== "prod")) {
-  console.error('buildExtension: --env <dev|prod> is required');
-  process.exit(1);
-}
-
-function replaceInIndex(from, to, label) {
-  const source = fs.readFileSync(indexPath, "utf8");
-
-  if (!source.includes(from)) {
-    if (source.includes(to)) {
-      console.log(`buildExtension: ${label} already set`);
-      return;
-    }
-    console.error(
-      `buildExtension: expected ${label} pattern not found in index.js`,
-    );
-    process.exit(1);
-  }
-
-  fs.writeFileSync(indexPath, source.replace(from, to), "utf8");
-  console.log(`buildExtension: ${label} → ${to}`);
-}
-
-function setLoadLocally(value) {
-  if (!fs.existsSync(indexPath)) {
-    console.error("buildExtension: extension/index.js not found");
-    process.exit(1);
-  }
-  const from = value ? LOAD_LOCALLY_FALSE : LOAD_LOCALLY_TRUE;
-  const to = value ? LOAD_LOCALLY_TRUE : LOAD_LOCALLY_FALSE;
-  replaceInIndex(from, to, "LOAD_LOCALLY");
-}
-
-function setRemoteActionsEnv(targetEnv) {
-  const from = targetEnv === "dev" ? REMOTE_ENV_PROD : REMOTE_ENV_DEV;
-  const to = targetEnv === "dev" ? REMOTE_ENV_DEV : REMOTE_ENV_PROD;
-  replaceInIndex(from, to, "REMOTE_ACTIONS_ENV");
-}
-
-let failed = false;
-
-try {
-  execFileSync("tsx", ["scripts/build.ts"], {
-    cwd: projectDir,
-    stdio: "inherit",
-  });
-
-  setLoadLocally(false);
-  setRemoteActionsEnv(env);
-
-  execFileSync("node", ["scripts/packageExtension.mjs"], {
-    cwd: projectDir,
-    stdio: "inherit",
-  });
-} catch {
-  failed = true;
-} finally {
-  try {
-    setLoadLocally(true);
-    setRemoteActionsEnv("prod");
-  } catch {
-    failed = true;
-  }
-}
-
-if (failed) {
-  process.exit(1);
-}

package/bin/packageExtension.mjs

@@ -1,29 +0,0 @@
-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);
-}