@foldspace_npm/harness 0.1.34 → 0.1.36

package/CLAUDE.md

@@ -319,6 +319,16 @@ and asking are not the only options — **observing is, and it comes first**:
    not open a path that does something (`/logout`, `/…/delete`); and `read`
    only goes to the app's own origin, a host configured for this project, or
    an origin `screen` saw the page call.
+
+   **A button you need to look behind** (a report tile, a "View details"):
+   ask the human first, naming it - *"May I click 'Staff Overview'? It's a
+   button, so it could do something."* Only after their yes in this chat, run
+   `npx foldspace observe screen --click "Staff Overview" --human-said-yes`.
+   One yes covers that one button, once. Never pass `--human-said-yes`
+   without it. Even with a yes, observe refuses a label that reads like an
+   action (Export, Send, Delete, Run…), a form submit, a download and signing
+   out: hand those to the human. If the result has `buttonWarning`, the button
+   sent changes to the server: tell the human what, in one line, first.
 3. **Ask the human to perform the workflow** — only for what you cannot reach:
    an MFA step, a paywall, a screen that needs a record the account does not
    have, or anything that would write.
@@ -327,7 +337,7 @@ Signing in is the human's step, because `inject` launches its own Chrome
 profile (empty the first time; it keeps the sign-in after that).
 Navigating is yours. **While you drive a signed-in account you are read-only:**
 GET only, never submit a form, never click anything that creates, sends or
-deletes.
+deletes, and a plain button only after the human's yes (above).
 
 Capture at least one real HTTP 200 for the data the action needs. If there is
 none, pivot; do not create Foldspace resources. Before that address goes into

package/bin/observe.mjs

@@ -6,7 +6,7 @@
  *
  *   foldspace observe pages
  *   foldspace observe menu
- *   foldspace observe screen [--click "<label>"] [--goto /path | https://<one of this project's hosts>/path] [--match "deal stage"] [--wait 4000]
+ *   foldspace observe screen [--click "<label>" [--human-said-yes]] [--goto /path | https://<one of this project's hosts>/path] [--match "deal stage"] [--wait 4000]
  *   foldspace observe read <path-or-url>
  *   foldspace observe auth [--wait 5000]
  *   foldspace observe styles
@@ -30,6 +30,7 @@ import {
   NAV_SCOPE_SELECTOR,
   analyzeAuthHeaders,
   buildAuthSummary,
+  buttonRefusal,
   clickRefusal,
   displayUrl,
   isCandidateRequest,
@@ -57,7 +58,7 @@ import { resolveProjectDir } from "../src/upgrade.mjs";
 const SUBCOMMANDS = {
   pages: { values: [], flags: [] },
   menu: { values: [], flags: [] },
-  screen: { values: ["click", "goto", "match", "wait"], flags: [] },
+  screen: { values: ["click", "goto", "match", "wait"], flags: ["human-said-yes"] },
   read: { values: [], flags: [] },
   auth: { values: ["wait"], flags: [] },
   styles: { values: [], flags: ["write"] },
@@ -124,11 +125,16 @@ async function evaluateInFrames(page, expression, { stopWhen } = {}) {
   return values;
 }
 
-/** Page code shared by `menu` (click = null) and `screen --click`. */
-function navigationScript(clickLabel) {
+/**
+ * Page code shared by `menu` (click = null) and `screen --click`. With
+ * humanSaidYes, a plain button anywhere on the page may be clicked too, once
+ * buttonRefusal lets its label through.
+ */
+function navigationScript(clickLabel, humanSaidYes = false) {
   return `(() => {
   ${pickByLabel}
   ${clickRefusal}
+  ${buttonRefusal}
   ${VISIBLE_JS}
   const labelOf = (el) =>
     (el.innerText || el.textContent || "").replace(/\\s+/g, " ").trim() ||
@@ -181,17 +187,48 @@ function navigationScript(clickLabel) {
   }
   const want = ${JSON.stringify(clickLabel ?? null)};
   if (want === null) return { items };
+  // A button the human said yes to: screened by buttonRefusal, then clicked.
+  const clickButton = (el, item) => {
+    const why = buttonRefusal(item);
+    if (why) return { clicked: false, refused: why };
+    el.click();
+    return { clicked: true, item, button: true };
+  };
   const index = pickByLabel(items, want);
   if (index < 0) {
     const lower = want.toLowerCase();
-    const elsewhere = [...document.querySelectorAll("a, button, input[type=submit], [role=button], [role=menuitem], [role=tab], [role=link]")]
-      .some((el) => visible(el) && (labelOf(el) || el.value || "").toLowerCase().includes(lower));
+    const anywhere = [...document.querySelectorAll("a, button, [role=button], [role=menuitem], [role=tab], [role=link]")]
+      .filter((el) => visible(el) && !el.closest("form") && (labelOf(el) || "").length <= 60);
+    const elsewhere = anywhere.some((el) => (labelOf(el) || "").toLowerCase().includes(lower));
+    if (${JSON.stringify(Boolean(humanSaidYes))} && elsewhere) {
+      const found = anywhere.map((el) => ({ el, label: labelOf(el) }));
+      const at = pickByLabel(found, want);
+      if (at >= 0) {
+        const el = found[at].el;
+        const href = el.getAttribute("href");
+        if (el.tagName === "A" && href && href !== "#" && !/^javascript:/i.test(href)) {
+          return { clicked: false, refused: '"' + found[at].label + '" is a link outside the navigation: open it with --goto ' + new URL(href, location.href).pathname + "." };
+        }
+        return clickButton(el, {
+          label: found[at].label,
+          kind: kindOf(el),
+          path: null,
+          submitsForm: false,
+          download: el.hasAttribute("download"),
+          filePicker: el.matches("input[type=file], label[for]"),
+          expands: el.hasAttribute("aria-expanded") || el.hasAttribute("aria-haspopup"),
+        });
+      }
+    }
     return { clicked: false, outsideNavigation: elsewhere, available: items.map((item) => item.label) };
   }
   const refused = clickRefusal(items[index]);
-  if (refused) return { clicked: false, refused };
-  elements[index].click();
-  return { clicked: true, item: items[index] };
+  if (!refused) {
+    elements[index].click();
+    return { clicked: true, item: items[index] };
+  }
+  if (!${JSON.stringify(Boolean(humanSaidYes))} || items[index].kind === "link" && items[index].path) return { clicked: false, refused };
+  return clickButton(elements[index], items[index]);
 })()`;
 }
 
@@ -388,7 +425,7 @@ async function runScreen(page, flags) {
     if (flags.click !== undefined) await network.settle(Math.min(waitMs, 3000));
   }
   if (flags.click !== undefined) {
-    const results = await evaluateInFrames(page, navigationScript(String(flags.click)), {
+    const results = await evaluateInFrames(page, navigationScript(String(flags.click), Boolean(flags["human-said-yes"])), {
       stopWhen: (value) => value?.clicked === true,
     });
     const hit = results.find((value) => value?.clicked);
@@ -398,7 +435,7 @@ async function runScreen(page, flags) {
       const error = refused
         ? refused.refused
         : outside
-          ? `"${flags.click}" is on the page but not in the app's navigation. observe only clicks navigation, never a control that could create, send, save or delete.`
+          ? `"${flags.click}" is on the page but not in the app's navigation. Ask the human in chat whether you may click it, naming it; only after their yes, run this again with --human-said-yes.`
           : `No navigation item is labelled "${flags.click}".`;
       throw new ObserveExit(
         {
@@ -409,7 +446,7 @@ async function runScreen(page, flags) {
         1,
       );
     }
-    reached = { how: "click", ...publicItem(hit.item) };
+    reached = { how: "click", ...publicItem(hit.item), ...(hit.button ? { button: true } : {}) };
   }
   if (!reached) {
     // Nothing to reach: reload so this screen's own requests are seen.
@@ -449,6 +486,7 @@ async function runScreen(page, flags) {
     writes.set(`${entry.method} ${entry.path}`, entry);
   }
   const ranked = rankCandidates(candidates, words, 8);
+  const buttonWrote = reached.button && writes.size > 0;
   return {
     ok: true,
     reached,
@@ -457,6 +495,9 @@ async function runScreen(page, flags) {
     requestsSeen: all.filter(isApiCall).length,
     candidates: ranked,
     writesSeen: [...writes.values()].slice(0, 20),
+    ...(buttonWrote
+      ? { buttonWarning: `The button "${reached.label}" sent ${writes.size} change(s) to the server (writesSeen). Tell the human what it sent, in one line, before anything else.` }
+      : {}),
     ...customerSubdomainFields(url, all.filter(isApiCall).map((request) => request.url)),
     ...(ranked.length
       ? {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/src/cdp-ownership.mjs

@@ -162,8 +162,12 @@ async function openCdpSocket(webSocketDebuggerUrl) {
 export async function inspectCdpUserDataDir(webSocketDebuggerUrl) {
   const session = await openCdpSocket(webSocketDebuggerUrl);
   try {
+    // background: true - a tab opened in front raises Chrome over whatever
+    // app the human is using, on every harness command (measured 2026-10-27:
+    // 3 of 3 in front, 0 in the background).
     const { targetId } = await session.call("Target.createTarget", {
       url: "chrome://version/",
+      background: true,
     });
     const attached = await session.call("Target.attachToTarget", {
       targetId,

package/src/cli-registry.mjs

@@ -371,6 +371,7 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     options: [
       value("--click", "label", "screen: reach the screen by a navigation label, as a person would"),
+      flag("--human-said-yes", "screen --click: the human said yes in chat to clicking this one plain button; a label that reads like an action is still refused"),
       value("--goto", "path", "screen: a path on this host, or a full https address on a host this project names"),
       value("--match", "words", "screen: rank the requests seen by these words"),
       value("--wait", "ms", "screen/auth: how long to keep listening"),

package/src/observe-core.mjs

@@ -233,6 +233,28 @@ export function clickRefusal(item) {
   return `"${label}" is a ${item?.kind || "button"} with no link behind it, and a button can do anything. observe clicks links, tabs and menu openers only - find the screen's path with \`menu\` and use --goto.`;
 }
 
+/**
+ * For a plain button the human has said yes to in chat (`screen --click
+ * "<label>" --human-said-yes`): why observe still will not click it, or null
+ * when it may. The yes covers looking, never acting, so a label that reads like
+ * an action, a form submit, a download, a file picker and signing out stay
+ * refused. Self-contained (injected into the page).
+ */
+export function buttonRefusal(item) {
+  const label = String(item?.label || "");
+  const text = label.replace(/^[^\p{L}\p{N}]+/u, "");
+  if (/\b(log|sign)[\s-]?(out|off)\b/i.test(text)) return `"${label}" ends the session; observe never clicks it.`;
+  if (item?.submitsForm) return `"${label}" submits a form; observe never clicks it, even with a yes.`;
+  if (item?.download) return `"${label}" downloads a file; observe never clicks it, even with a yes.`;
+  if (item?.filePicker) return `"${label}" opens a file picker; observe never clicks it, even with a yes.`;
+  const acts =
+    /\b(delete|remove|destroy|erase|purge|empty|clear|reset|revoke|regenerate|rotate|deactivate|disable|enable|activate|suspend|terminate|cancel|confirm|approve|reject|decline|accept|submit|send|resend|email|share|save|create|add(?![- ]?ons)|new|invite|pay|buy|purchase|charge|refund|upgrade|downgrade|subscribe|unsubscribe|publish|unpublish|archive|restore|import|export|download|upload|print|run|execute|start|stop|pause|resume|merge|transfer|assign|mark|bulk|sync|connect|disconnect|install|uninstall|generate|update|edit|apply|book|schedule|place|checkout|sign|join|leave|follow|unfollow|like|vote)\b/i;
+  const hit = text.match(acts);
+  return hit
+    ? `"${label}" reads like an action ("${hit[1]}"), and a yes covers looking, never acting. Hand this step to the human.`
+    : null;
+}
+
 // ------------------------------------------------------------ JSON shapes
 
 /**