@foldspace_npm/harness 0.1.15 → 0.1.16

package/package.json

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

package/src/cdp-client.mjs

@@ -0,0 +1,233 @@
+// A small CDP page client for the read-only verbs (`observe`, `ask`, `run`).
+//
+// It is a second client on the inject Chrome and is safe to use while
+// `foldspace attach` is running: attach's claim on the debug port is about
+// request interception (`Fetch.enable`) and navigation, and nothing here
+// enables Fetch. `Runtime.evaluate`, `Network.enable` and
+// `Page.captureScreenshot` from a second client do not disturb it.
+//
+// Uses the global WebSocket, as bin/attach.mjs does.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { assertOwnedCdp, chromeProfileDir, ownershipErrorMessage } from "./cdp-ownership.mjs";
+import { resolveProjectDir } from "./upgrade.mjs";
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Where inject recorded the Chrome it launched. Never guess a port. */
+export function readLaunchState(projectDir = resolveProjectDir()) {
+  const statePath = path.join(projectDir, ".foldspace-dev", "state.json");
+  if (!fs.existsSync(statePath)) {
+    throw new Error(
+      "No .foldspace-dev/state.json here. Run `npm run inject` first, from the project folder.",
+    );
+  }
+  const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  const port = process.env.CDP_PORT || state.debugPort;
+  if (!port) throw new Error("state.json has no debugPort. Run `npm run inject` again.");
+  const hosts = state.resolvedTarget?.hosts || [];
+  return {
+    projectDir,
+    port: String(port),
+    hosts,
+    target: state.resolvedTarget || {},
+    sentinel: state.sentinel,
+    profileDir: chromeProfileDir(projectDir),
+  };
+}
+
+async function listTargets(port) {
+  let response;
+  try {
+    response = await fetch(`http://127.0.0.1:${port}/json/list`);
+  } catch {
+    throw new Error(
+      `The inject Chrome is not answering on :${port}. It was closed; run \`npm run inject\` again.`,
+    );
+  }
+  return response.json();
+}
+
+function hostMatches(url, hosts) {
+  try {
+    const host = new URL(url).hostname;
+    return hosts.some((pattern) => {
+      const bare = String(pattern).replace(/^\*\./, "");
+      return host === bare || host.endsWith(`.${bare}`);
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The human's tab: the page on the product's host. When the project names its
+ * hosts and no tab is on one of them, that is an error, never "the first tab":
+ * these commands reload, click and read with a session attached, and the first
+ * tab may be anything the human opened.
+ */
+export function choosePage(pages, hosts = []) {
+  const real = pages.filter(
+    (target) => target.type === "page" && !String(target.url).startsWith("devtools://"),
+  );
+  if (!real.length) throw new Error("The test window has no open page.");
+  const match = real.find((page) => hostMatches(page.url, hosts));
+  if (match) return match;
+  if (hosts.length) {
+    throw new Error(
+      `The test window has no tab on ${hosts.join(", ")}. Open the product there (or finish signing in), then try again.`,
+    );
+  }
+  return real[0];
+}
+
+export async function pickPage(port, hosts = []) {
+  return choosePage(await listTargets(port), hosts);
+}
+
+// One check per process: it opens a browser-level session.
+let ownershipVerified = false;
+
+/**
+ * Prove the Chrome on this port is the one `inject` launched for THIS project -
+ * same check as `attach`. A stale port, or CDP_PORT pointing elsewhere, would
+ * otherwise have these commands reload and click in someone else's browser.
+ */
+export async function assertTestWindow(state, verify = assertOwnedCdp) {
+  if (ownershipVerified) return;
+  const owned = await verify({ profileDir: state.profileDir, port: state.port, token: state.sentinel });
+  if (!owned.ok) {
+    throw new Error(
+      ownershipErrorMessage(owned.reason, {
+        port: state.port,
+        profileDir: state.profileDir,
+        root: state.projectDir,
+      }),
+    );
+  }
+  ownershipVerified = true;
+}
+
+export class CdpPage {
+  #socket;
+  #nextId = 0;
+  #pending = new Map();
+  #listeners = new Map();
+
+  constructor(socket, info) {
+    this.#socket = socket;
+    this.info = info;
+    socket.addEventListener("message", (event) => this.#dispatch(JSON.parse(event.data)));
+  }
+
+  static async open({ projectDir } = {}) {
+    const state = readLaunchState(projectDir);
+    await assertTestWindow(state);
+    const page = await pickPage(state.port, state.hosts);
+    const socket = new WebSocket(page.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => {
+      socket.addEventListener("open", resolve, { once: true });
+      socket.addEventListener("error", () => reject(new Error("Could not open the CDP socket.")), {
+        once: true,
+      });
+    });
+    const client = new CdpPage(socket, { ...state, url: page.url, title: page.title });
+    await client.send("Runtime.enable");
+    await client.send("Page.enable");
+    return client;
+  }
+
+  #dispatch(message) {
+    if (message.id && this.#pending.has(message.id)) {
+      const { resolve, reject } = this.#pending.get(message.id);
+      this.#pending.delete(message.id);
+      if (message.error) reject(new Error(message.error.message));
+      else resolve(message.result);
+      return;
+    }
+    for (const listener of this.#listeners.get(message.method) || []) listener(message.params);
+  }
+
+  send(method, params = {}, { timeoutMs = 30000 } = {}) {
+    const id = ++this.#nextId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.#pending.delete(id)) {
+          reject(new Error(`CDP ${method} did not answer within ${timeoutMs}ms.`));
+        }
+      }, timeoutMs);
+      this.#pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      this.#socket.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  on(method, listener) {
+    if (!this.#listeners.has(method)) this.#listeners.set(method, []);
+    this.#listeners.get(method).push(listener);
+  }
+
+  /** Evaluate the body of an async function in the page; returns its JSON value. */
+  async evaluate(body, { timeoutMs = 30000 } = {}) {
+    const result = await this.send(
+      "Runtime.evaluate",
+      { expression: `(async () => { ${body} })()`, awaitPromise: true, returnByValue: true },
+      { timeoutMs },
+    );
+    if (result.exceptionDetails) {
+      throw new Error(
+        result.exceptionDetails.exception?.description ||
+          result.exceptionDetails.text ||
+          "evaluate failed",
+      );
+    }
+    return result.result?.value;
+  }
+
+  /** PNG screenshot of the viewport, or of `clip` ({x,y,width,height}). */
+  async screenshot(filePath, clip) {
+    const params = { format: "png" };
+    if (clip) params.clip = { ...clip, scale: 1 };
+    const shot = await this.send("Page.captureScreenshot", params);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, Buffer.from(shot.data, "base64"));
+    return filePath;
+  }
+
+  close() {
+    try {
+      this.#socket.close();
+    } catch {
+      // already closed
+    }
+  }
+}
+
+/** Parse `--flag value` / `--flag` out of argv; returns { flags, rest }. */
+export function parseArgs(argv, valueFlags = []) {
+  const flags = {};
+  const rest = [];
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      if (valueFlags.includes(name)) flags[name] = argv[++index];
+      else flags[name] = true;
+    } else rest.push(arg);
+  }
+  return { flags, rest };
+}
+
+export function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}

package/src/cli-help.mjs

@@ -49,7 +49,8 @@ export function renderGeneralHelp(registry) {
     "  foldspace upgrade --check        Compare the installed pin to npm latest",
     "",
     "attach loads local actions and observes the normal agent experience.",
-    "deploy is a separate remote publication step.",
+    "observe, ask and run look at and test that experience without the customer's help.",
+    ...(registry.publishWorkflow.length ? ["deploy is a separate remote publication step."] : []),
   );
   return sections.join("\n");
 }

package/src/cli-registry.mjs

@@ -276,8 +276,53 @@ export const CLI_COMMANDS = Object.freeze([
       "Detach with Ctrl-C, or foldspace attach --stop for a daemon",
     ],
   }),
+  Object.freeze({
+    name: "observe",
+    entry: "observe.mjs",
+    group: "verify",
+    summary: "Look at the signed-in test window, read-only: screens, requests, auth, styles",
+    usage:
+      "foldspace observe <pages|menu|screen|read|auth|styles|screenshot|wait-login> [options]",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate"],
+    positionals: [
+      Object.freeze({
+        name: "verb",
+        required: true,
+        description:
+          "pages | menu | screen | read <path> | auth | styles | screenshot | wait-login",
+      }),
+      Object.freeze({
+        name: "path",
+        required: false,
+        description: "read: the GET path or same-site URL to replay",
+      }),
+    ],
+    options: [
+      value("--click", "label", "screen: reach the screen by a navigation label, as a person would"),
+      value("--goto", "path", "screen: a same-origin path"),
+      value("--match", "words", "screen: rank the requests seen by these words"),
+      value("--wait", "ms", "screen/auth: how long to keep listening"),
+      value("--out", "file", "screenshot: where to save the PNG"),
+      value("--timeout", "seconds", "wait-login: give up after this long", { default: "600" }),
+    ],
+    prerequisites: ["foldspace inject has opened the test window"],
+    effects: [
+      "GET only. Never submits a form; clicks navigation elements only",
+      "Prints names, shapes and counts - never values, tokens or cookies",
+      "Works while foldspace attach is running",
+    ],
+    next: ["Record what you established in docs/app-profile.md", "Write the handler"],
+  }),
   Object.freeze({
     name: "deploy",
+    // Foldspace-internal: it uploads to Foldspace's own storage, which no
+    // customer can write to. It stays runnable (the deploy pipeline calls it)
+    // but is left out of help unless FOLDSPACE_INTERNAL=1, because a coding
+    // agent that finds it in the contract offers it to the customer.
+    internal: true,
     entry: "deploy.mjs",
     group: "publish",
     summary: "Publish dist/index.js to remote Foldspace action storage",
@@ -351,7 +396,9 @@ export function commandByName(name) {
   return CLI_COMMANDS.find((command) => command.name === name) || null;
 }
 
-export function createCliRegistry({ packageName, packageVersion }) {
+export function createCliRegistry({ packageName, packageVersion, env = process.env }) {
+  const showInternal = env.FOLDSPACE_INTERNAL === "1";
+  const visible = CLI_COMMANDS.filter((command) => showInternal || !command.internal);
   const diagnostics = diagnosticCatalogue()
     .filter((diagnostic) => PUBLIC_DIAGNOSTICS.has(diagnostic.name))
     .map((diagnostic) => ({
@@ -368,7 +415,8 @@ export function createCliRegistry({ packageName, packageVersion }) {
     },
     protocolVersion: HARNESS_PROTOCOL_VERSION,
     workflow: ["init", "build", "inject", "attach"],
-    publishWorkflow: ["deploy"],
+    verifyWorkflow: ["observe"],
+    publishWorkflow: showInternal ? ["deploy"] : [],
     capabilities: CAPABILITY_CATALOGUE.map(([id, description]) => ({
       id,
       description,
@@ -378,7 +426,7 @@ export function createCliRegistry({ packageName, packageVersion }) {
       id,
       description,
     })),
-    commands: CLI_COMMANDS.map(({ entry: _entry, ...command }) => command),
+    commands: visible.map(({ entry: _entry, internal: _internal, ...command }) => command),
     diagnostics,
     notes: [
       "Capability metadata describes current behavior; it is not hosted-environment enforcement.",
@@ -387,6 +435,8 @@ export function createCliRegistry({ packageName, packageVersion }) {
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
       "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
       "If update.outdated is true, ask the user before foldspace upgrade --yes.",
+      "observe, ask and run are read-only second clients on the test window and work while attach runs.",
+      "There is no customer-run publication step: putting actions in front of end users is done with Foldspace's team.",
     ],
   };
 }