@foldspace_npm/harness 0.1.15 → 0.1.16

package/bin/observe.mjs

@@ -0,0 +1,790 @@
+#!/usr/bin/env node
+/**
+ * foldspace observe — read-only eyes on the Chrome that `foldspace inject`
+ * launched, so nobody hand-writes a CDP script to find where an action's data
+ * lives.
+ *
+ *   foldspace observe pages
+ *   foldspace observe menu
+ *   foldspace observe screen [--click "<label>"] [--goto /path] [--match "deal stage"] [--wait 4000]
+ *   foldspace observe read <path-or-url>
+ *   foldspace observe auth [--wait 5000]
+ *   foldspace observe styles
+ *   foldspace observe screenshot [--out file.png]
+ *   foldspace observe wait-login [--timeout 600]
+ *
+ * Every subcommand prints ONE JSON document. It is safe beside a running
+ * `foldspace attach`: it never enables the Fetch domain, only navigates for
+ * `screen`/`auth`, only clicks the app's own navigation, only sends GET, and
+ * prints names and shapes — never a header, cookie or storage value.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import { CdpPage, parseArgs, printJson, readLaunchState, sleep } from "../src/cdp-client.mjs";
+import {
+  NAV_ITEM_SELECTOR,
+  NAV_SCOPE_SELECTOR,
+  analyzeAuthHeaders,
+  buildAuthSummary,
+  clickRefusal,
+  displayUrl,
+  isCandidateRequest,
+  isSameSite,
+  isStandardHeader,
+  looksLoggedIn,
+  parseMatchWords,
+  pickByLabel,
+  planRead,
+  printableUrl,
+  rankCandidates,
+  readHint,
+  refuseWriteFlags,
+  sameOriginPath,
+  summarizeJson,
+  toHex,
+} from "../src/observe-core.mjs";
+import { recordEvent } from "../src/session-events.mjs";
+import { resolveProjectDir } from "../src/upgrade.mjs";
+
+const SUBCOMMANDS = {
+  pages: { values: [], flags: [] },
+  menu: { values: [], flags: [] },
+  screen: { values: ["click", "goto", "match", "wait"], flags: [] },
+  read: { values: [], flags: [] },
+  auth: { values: ["wait"], flags: [] },
+  styles: { values: [], flags: [] },
+  screenshot: { values: ["out"], flags: [] },
+  "wait-login": { values: ["timeout"], flags: [] },
+};
+
+const projectDir = resolveProjectDir();
+
+class ObserveExit extends Error {
+  constructor(document, code) {
+    super(document.error || "observe");
+    this.document = document;
+    this.code = code;
+  }
+}
+
+function numberFlag(value, fallback, name) {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) throw new Error(`--${name} takes a number.`);
+  return parsed;
+}
+
+// ------------------------------------------------------------ page helpers
+
+const VISIBLE_JS = `const visible = (el) => {
+  if (!el.getClientRects().length) return false;
+  const style = getComputedStyle(el);
+  return style.visibility !== "hidden" && style.display !== "none";
+};`;
+
+/**
+ * Run an expression in the top frame and every child frame of this target,
+ * each in an isolated world: the DOM is shared, the app's own JavaScript is
+ * not touched. Apps that render inside an iframe keep their menu there.
+ */
+async function evaluateInFrames(page, expression, { stopWhen } = {}) {
+  const tree = await page.send("Page.getFrameTree");
+  const frames = [];
+  (function walk(node) {
+    frames.push(node.frame);
+    (node.childFrames || []).forEach(walk);
+  })(tree.frameTree);
+  const values = [];
+  for (const frame of frames) {
+    try {
+      const world = await page.send("Page.createIsolatedWorld", {
+        frameId: frame.id,
+        worldName: "foldspace-observe",
+      });
+      const result = await page.send("Runtime.evaluate", {
+        contextId: world.executionContextId,
+        expression,
+        returnByValue: true,
+      });
+      if (result.exceptionDetails) continue;
+      values.push(result.result?.value);
+      if (stopWhen && stopWhen(result.result?.value)) break;
+    } catch {
+      // a frame that went away mid-read is not an error
+    }
+  }
+  return values;
+}
+
+/** Page code shared by `menu` (click = null) and `screen --click`. */
+function navigationScript(clickLabel) {
+  return `(() => {
+  ${pickByLabel}
+  ${clickRefusal}
+  ${VISIBLE_JS}
+  const labelOf = (el) =>
+    (el.innerText || el.textContent || "").replace(/\\s+/g, " ").trim() ||
+    (el.getAttribute("aria-label") || "").trim() ||
+    (el.getAttribute("title") || "").trim();
+  const kindOf = (el) => {
+    const role = el.getAttribute("role");
+    if (role === "menuitem" || role === "tab" || role === "link") return role;
+    return el.tagName === "A" ? "link" : "button";
+  };
+  const items = [];
+  const elements = [];
+  const seenElements = new Set();
+  const seenKeys = new Set();
+  for (const scope of document.querySelectorAll(${JSON.stringify(NAV_SCOPE_SELECTOR)})) {
+    for (const el of scope.querySelectorAll(${JSON.stringify(NAV_ITEM_SELECTOR)})) {
+      if (seenElements.has(el)) continue;
+      seenElements.add(el);
+      if (!visible(el)) continue;
+      // A <header> also heads dialogs, cards and table rows; controls inside
+      // those, or inside a form, are not the app's navigation.
+      if (el.closest("dialog, [role=dialog], [role=alertdialog], form, table, [role=row], article")) continue;
+      const label = labelOf(el);
+      if (!label || label.length > 60) continue;
+      let path = null;
+      const href = el.getAttribute("href");
+      if (href && href !== "#" && !/^javascript:/i.test(href)) {
+        try {
+          const url = new URL(href, location.href);
+          if (url.origin !== location.origin) continue; // leaves the app
+          path = url.pathname + url.search + url.hash;
+        } catch {
+          continue;
+        }
+      }
+      const key = label + " " + path;
+      if (seenKeys.has(key)) continue;
+      seenKeys.add(key);
+      items.push({
+        label,
+        kind: kindOf(el),
+        path,
+        submitsForm: el.tagName === "BUTTON" && Boolean(el.form) && (el.type || "submit") === "submit",
+        download: el.hasAttribute("download"),
+        expands:
+          el.hasAttribute("aria-expanded") || el.hasAttribute("aria-haspopup") || el.hasAttribute("aria-controls"),
+      });
+      elements.push(el);
+    }
+  }
+  const want = ${JSON.stringify(clickLabel ?? null)};
+  if (want === null) return { items };
+  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));
+    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] };
+})()`;
+}
+
+// Origins this page was seen calling for its own data. `read` may go to these
+// and nowhere else off-origin. Kept beside the launch state, never in docs/.
+const ORIGINS_FILE = path.join(projectDir, ".foldspace-dev", "observe", "origins.json");
+
+function loadObservedOrigins() {
+  try {
+    const list = JSON.parse(fs.readFileSync(ORIGINS_FILE, "utf8"));
+    return Array.isArray(list) ? list.filter((entry) => typeof entry === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+function rememberObservedOrigins(urls, pageUrl, hosts) {
+  const known = new Set(loadObservedOrigins());
+  const before = known.size;
+  for (const url of urls) {
+    // The page really called it, AND it looks like the same site. Neither
+    // alone is enough: analytics hosts are called too.
+    if (!isSameSite(url, pageUrl, hosts)) continue;
+    try {
+      known.add(new URL(url).origin);
+    } catch {}
+  }
+  if (known.size === before) return;
+  fs.mkdirSync(path.dirname(ORIGINS_FILE), { recursive: true });
+  fs.writeFileSync(ORIGINS_FILE, `${JSON.stringify([...known].slice(-20), null, 2)}\n`, "utf8");
+}
+
+const publicItem = ({ label, kind, path: itemPath }) => ({ label, kind, path: itemPath });
+
+function recordNetwork(page) {
+  const requests = new Map();
+  const extraHeaders = new Map();
+  const inflight = new Set();
+  let lastActivity = Date.now();
+  page.on("Network.requestWillBeSent", (event) => {
+    lastActivity = Date.now();
+    inflight.add(event.requestId);
+    requests.set(event.requestId, {
+      id: event.requestId,
+      method: event.request.method,
+      url: event.request.url,
+      type: event.type,
+      headers: event.request.headers || {},
+    });
+  });
+  page.on("Network.requestWillBeSentExtraInfo", (event) => {
+    extraHeaders.set(event.requestId, event.headers || {});
+  });
+  page.on("Network.responseReceived", (event) => {
+    lastActivity = Date.now();
+    const request = requests.get(event.requestId);
+    if (!request) return;
+    request.status = event.response.status;
+    request.mimeType = event.response.mimeType;
+    request.type = event.type || request.type;
+  });
+  page.on("Network.loadingFinished", (event) => {
+    lastActivity = Date.now();
+    inflight.delete(event.requestId);
+    const request = requests.get(event.requestId);
+    if (request) request.finished = true;
+  });
+  page.on("Network.loadingFailed", (event) => {
+    inflight.delete(event.requestId);
+  });
+  return {
+    requests,
+    extraHeaders,
+    /** Wait until the network has been quiet for a moment, at most maxMs. */
+    async settle(maxMs) {
+      const started = Date.now();
+      while (Date.now() - started < maxMs) {
+        await sleep(150);
+        const quiet = inflight.size === 0 && Date.now() - lastActivity >= 1200;
+        if (quiet && Date.now() - started >= 1500) break;
+      }
+    },
+    async jsonBody(requestId) {
+      try {
+        const body = await page.send("Network.getResponseBody", { requestId }, { timeoutMs: 8000 });
+        const text = body.base64Encoded ? Buffer.from(body.body, "base64").toString("utf8") : body.body;
+        return JSON.parse(text);
+      } catch {
+        return undefined; // evicted, navigated away, or not JSON after all
+      }
+    },
+  };
+}
+
+const isApiCall = (request) => /^(xhr|fetch)$/i.test(request.type || "");
+
+// ------------------------------------------------------------- subcommands
+
+async function runPages() {
+  const state = readLaunchState(projectDir);
+  let targets;
+  try {
+    targets = await (await fetch(`http://127.0.0.1:${state.port}/json/list`)).json();
+  } catch {
+    throw new Error(
+      `The inject Chrome is not answering on :${state.port}. It was closed; run \`npm run inject\` again.`,
+    );
+  }
+  const pages = targets
+    .filter((target) => target.type === "page" && !String(target.url).startsWith("devtools://"))
+    .map((target) => ({ url: printableUrl(target.url), title: target.title }));
+  return { ok: true, pages };
+}
+
+async function runMenu(page) {
+  const perFrame = await evaluateInFrames(page, navigationScript(null));
+  const seen = new Set();
+  const items = [];
+  for (const entry of perFrame.flatMap((value) => value?.items || [])) {
+    const key = `${entry.label} ${entry.path}`;
+    if (seen.has(key) || items.length >= 60) continue;
+    seen.add(key);
+    items.push(publicItem(entry));
+  }
+  const url = await page.evaluate("return location.href;");
+  return {
+    ok: true,
+    url: printableUrl(url),
+    count: items.length,
+    items,
+    ...(items.length ? {} : { note: "No visible navigation found. The app may still be loading, or showing a login page." }),
+  };
+}
+
+async function runScreen(page, flags) {
+  const waitMs = numberFlag(flags.wait, 4000, "wait");
+  const words = parseMatchWords(flags.match);
+  const before = await page.evaluate("return location.href;");
+  const destination = flags.goto !== undefined ? sameOriginPath(flags.goto, before) : null;
+
+  await page.send("Network.enable");
+  const network = recordNetwork(page);
+  let reached;
+
+  if (destination) {
+    await page.send("Page.navigate", { url: destination.url });
+    reached = { how: "goto", path: destination.path };
+    if (flags.click !== undefined) await network.settle(Math.min(waitMs, 3000));
+  }
+  if (flags.click !== undefined) {
+    const results = await evaluateInFrames(page, navigationScript(String(flags.click)), {
+      stopWhen: (value) => value?.clicked === true,
+    });
+    const hit = results.find((value) => value?.clicked);
+    if (!hit) {
+      const refused = results.find((value) => value?.refused);
+      const outside = results.some((value) => value?.outsideNavigation);
+      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.`
+          : `No navigation item is labelled "${flags.click}".`;
+      throw new ObserveExit(
+        {
+          ok: false,
+          error,
+          available: [...new Set(results.flatMap((value) => value?.available || []))].slice(0, 40),
+        },
+        1,
+      );
+    }
+    reached = { how: "click", ...publicItem(hit.item) };
+  }
+  if (!reached) {
+    // Nothing to reach: reload so this screen's own requests are seen.
+    await page.send("Page.reload");
+    reached = { how: "reload" };
+  }
+  await network.settle(waitMs);
+
+  const url = await page.evaluate("return location.href;").catch(() => before);
+  const origin = new URL(url).origin;
+  const all = [...network.requests.values()];
+  const candidates = [];
+  const seenUrls = new Set();
+  for (const request of all) {
+    if (!request.finished || !isCandidateRequest(request) || seenUrls.has(request.url)) continue;
+    if (candidates.length >= 40) break;
+    seenUrls.add(request.url);
+    const json = await network.jsonBody(request.id);
+    if (json === undefined) continue;
+    const shape = summarizeJson(json);
+    candidates.push({
+      method: request.method,
+      path: displayUrl(request.url, origin),
+      status: request.status,
+      contentType: request.mimeType,
+      topLevelKeys: shape.topLevelKeys,
+      rows: shape.rows,
+      fieldNames: shape.fieldNames,
+    });
+  }
+  rememberObservedOrigins([...seenUrls], url, page.info.hosts);
+  const writes = new Map();
+  for (const request of all) {
+    if (!isApiCall(request) || /^(GET|HEAD|OPTIONS)$/i.test(request.method)) continue;
+    // No query either: a write's query string is as much payload as its body.
+    const entry = { method: request.method, path: displayUrl(request.url, origin, { query: false }) };
+    writes.set(`${entry.method} ${entry.path}`, entry);
+  }
+  const ranked = rankCandidates(candidates, words, 8);
+  return {
+    ok: true,
+    reached,
+    url: printableUrl(url),
+    matchedOn: words,
+    requestsSeen: all.filter(isApiCall).length,
+    candidates: ranked,
+    writesSeen: [...writes.values()].slice(0, 20),
+    ...(ranked.length
+      ? {}
+      : { note: "No successful JSON GET was seen. The data may load after another click, or arrive inside the HTML." }),
+  };
+}
+
+async function runRead(page, flags, rest) {
+  const pageUrl = await page.evaluate("return location.href;");
+  const plan = planRead({
+    target: rest[0],
+    flags,
+    extra: rest.slice(1),
+    pageUrl,
+    hosts: page.info.hosts,
+    observedOrigins: loadObservedOrigins(),
+  });
+  const result = await page.evaluate(
+    `${summarizeJson}
+    const response = await fetch(${JSON.stringify(plan.url)}, {
+      method: "GET",
+      credentials: "include",
+      headers: { Accept: "application/json" },
+    });
+    const text = await response.text();
+    const out = {
+      status: response.status,
+      ok: response.ok,
+      contentType: response.headers.get("content-type"),
+      json: false,
+      bytes: text.length,
+    };
+    try {
+      Object.assign(out, summarizeJson(JSON.parse(text)), { json: true });
+    } catch {}
+    return out;`,
+  );
+  const hint = readHint(result.status);
+  const { status, ok, ...shape } = result;
+  return {
+    ok,
+    status,
+    method: "GET",
+    path: displayUrl(plan.url, new URL(pageUrl).origin),
+    ...shape,
+    ...(hint ? { hint } : {}),
+  };
+}
+
+async function runAuth(page, flags) {
+  const waitMs = numberFlag(flags.wait, 5000, "wait");
+  await page.send("Network.enable");
+  const network = recordNetwork(page);
+  await page.send("Page.reload");
+  await network.settle(waitMs);
+
+  const url = await page.evaluate("return location.href;");
+  const origin = new URL(url).origin;
+  const calls = [...network.requests.values()].filter(
+    (request) => isApiCall(request) && isSameSite(request.url, url, page.info.hosts),
+  );
+
+  // Real values are gathered here to be COMPARED; none of them is returned.
+  const pageSources = await page.evaluate(`
+    const dump = (storage) => {
+      const out = {};
+      try {
+        for (let index = 0; index < storage.length && index < 200; index++) {
+          const key = storage.key(index);
+          out[key] = storage.getItem(key);
+        }
+      } catch {}
+      return out;
+    };
+    return {
+      localStorage: dump(window.localStorage),
+      sessionStorage: dump(window.sessionStorage),
+      metas: [...document.querySelectorAll("meta[name][content], meta[property][content]")].map((meta) => ({
+        name: meta.getAttribute("name") || meta.getAttribute("property"),
+        content: meta.getAttribute("content"),
+      })),
+    };`);
+  const cookies = await page
+    .send("Network.getCookies", { urls: [url] })
+    .then((result) => result.cookies || [])
+    .catch(() => []);
+  const responses = [];
+  for (const request of calls) {
+    if (!request.finished || !/json/i.test(request.mimeType || "") || responses.length >= 30) continue;
+    const json = await network.jsonBody(request.id);
+    if (json === undefined) continue;
+    responses.push({
+      request: `${request.method} ${displayUrl(request.url, origin, { query: false })}`,
+      json,
+    });
+  }
+
+  const observed = calls.map((request) => ({
+    method: request.method,
+    path: displayUrl(request.url, origin, { query: false }),
+    // ExtraInfo is what really went on the wire; the page-set names keep their case.
+    headers: { ...lowerKeys(network.extraHeaders.get(request.id), request.headers), ...request.headers },
+  }));
+  const headers = analyzeAuthHeaders(observed, { ...pageSources, cookies, responses });
+
+  // Does a plain cookie-only GET get through? Prefer a request the app dressed
+  // up with its own headers: that is the one whose answer tells us something.
+  const replayable = calls.filter((request) => request.finished && isCandidateRequest(request));
+  const custom = (request) => Object.keys(request.headers).filter((name) => !isStandardHeader(name));
+  const probe =
+    replayable.find((request) => custom(request).length && new URL(request.url).origin === origin) ||
+    replayable.find((request) => new URL(request.url).origin === origin) ||
+    replayable[0];
+  let cookieOnlyGet = null;
+  if (probe) {
+    const answer = await page
+      .evaluate(
+        `try {
+          const response = await fetch(${JSON.stringify(probe.url)}, {
+            method: "GET",
+            credentials: "include",
+            headers: { Accept: "application/json" },
+          });
+          return { status: response.status, ok: response.ok };
+        } catch (error) {
+          return { status: 0, ok: false, error: "blocked before it was sent (CORS)" };
+        }`,
+      )
+      .catch(() => ({ status: 0, ok: false }));
+    cookieOnlyGet = {
+      path: displayUrl(probe.url, origin, { query: false }),
+      ...answer,
+      appSentHeaders: custom(probe),
+    };
+  }
+
+  return {
+    ok: true,
+    url: printableUrl(url),
+    requestsSeen: calls.length,
+    headers,
+    cookieNames: cookies.map((cookie) => ({ name: cookie.name, httpOnly: cookie.httpOnly })).slice(0, 30),
+    cookieOnlyGet,
+    summary: buildAuthSummary({ headers, cookieOnlyGet }),
+  };
+}
+
+/** Wire headers whose name the page did not already set (HTTP/2 lowercases them). */
+function lowerKeys(wire = {}, pageSet = {}) {
+  const known = new Set(Object.keys(pageSet).map((name) => name.toLowerCase()));
+  return Object.fromEntries(Object.entries(wire).filter(([name]) => !known.has(name.toLowerCase())));
+}
+
+async function runStyles(page) {
+  const raw = await page.evaluate(`
+    ${VISIBLE_JS}
+    const clear = (color) =>
+      !color || color === "transparent" || /,\\s*0\\)$/.test(color) || /\\/\\s*0\\)$/.test(color);
+    const top = (tally) => [...tally.entries()].sort((a, b) => b[1] - a[1]).map(([value]) => value);
+    const bump = (tally, value, weight = 1) => tally.set(value, (tally.get(value) || 0) + weight);
+    const body = getComputedStyle(document.body);
+
+    // What is actually painted behind the content, not what <body> declares.
+    const viewport = { width: innerWidth, height: innerHeight };
+    const behind = document
+      .elementsFromPoint(viewport.width / 2, viewport.height / 2)
+      .find((el) => {
+        const rect = el.getBoundingClientRect();
+        return (
+          rect.width >= viewport.width * 0.6 &&
+          rect.height >= viewport.height * 0.6 &&
+          !clear(getComputedStyle(el).backgroundColor)
+        );
+      });
+    // A short <body> still paints the whole canvas, so it is the next best answer.
+    const background =
+      [behind, document.body, document.documentElement]
+        .filter(Boolean)
+        .map((el) => getComputedStyle(el).backgroundColor)
+        .find((color) => !clear(color)) || "rgb(255, 255, 255)";
+
+    const fonts = new Map(), sizes = new Map(), colors = new Map();
+    for (const el of [...document.querySelectorAll("p, span, div, li, td, th, label, h1, h2, h3, h4, a")].slice(0, 3000)) {
+      const own = [...el.childNodes]
+        .filter((node) => node.nodeType === 3)
+        .map((node) => node.textContent.trim())
+        .join("");
+      if (!own || !visible(el)) continue;
+      const style = getComputedStyle(el);
+      bump(fonts, style.fontFamily, own.length);
+      bump(sizes, style.fontSize, own.length);
+      if (el.tagName !== "A") bump(colors, style.color, own.length);
+    }
+
+    const links = new Map();
+    for (const el of [...document.querySelectorAll("a[href]")].slice(0, 500)) {
+      if (visible(el) && clear(getComputedStyle(el).backgroundColor)) bump(links, getComputedStyle(el).color);
+    }
+
+    // Primary button: filled, button-sized, and the most saturated large one.
+    let button = null;
+    for (const el of document.querySelectorAll("button, [role=button], a, input[type=submit]")) {
+      if (!visible(el)) continue;
+      const style = getComputedStyle(el);
+      if (clear(style.backgroundColor) || style.backgroundColor === background) continue;
+      const rect = el.getBoundingClientRect();
+      const label = (el.innerText || el.value || "").trim();
+      if (!label || label.length > 40 || rect.height > 80 || rect.width > 420 || rect.height < 16) continue;
+      const channels = (style.backgroundColor.match(/[\\d.]+/g) || []).slice(0, 3).map(Number);
+      const chroma = (Math.max(...channels) - Math.min(...channels)) / 255;
+      const score = (chroma > 0.15 ? 1e7 : 0) + rect.width * rect.height;
+      if (!button || score > button.score) {
+        button = {
+          score,
+          background: style.backgroundColor,
+          color: style.color,
+          borderRadius: style.borderTopLeftRadius,
+          fontWeight: style.fontWeight,
+        };
+      }
+    }
+
+    const borders = new Map(), radii = new Map();
+    const boxes = "input:not([type=hidden]), select, textarea, table, th, td, section, article, [class*=card i], [class*=panel i], [class*=tile i]";
+    for (const el of [...document.querySelectorAll(boxes)].slice(0, 1500)) {
+      if (!visible(el)) continue;
+      const style = getComputedStyle(el);
+      for (const side of ["Top", "Bottom"]) {
+        if (parseFloat(style["border" + side + "Width"]) > 0 && style["border" + side + "Style"] !== "none" && !clear(style["border" + side + "Color"])) {
+          bump(borders, style["border" + side + "Color"]);
+        }
+      }
+      if (parseFloat(style.borderTopLeftRadius) > 0) bump(radii, style.borderTopLeftRadius);
+    }
+
+    return {
+      url: location.href,
+      body: { fontFamily: body.fontFamily, fontSize: body.fontSize, color: body.color },
+      fontFamily: top(fonts)[0] || body.fontFamily,
+      fontSize: top(sizes)[0] || body.fontSize,
+      text: top(colors)[0] || body.color,
+      textMuted: top(colors)[1] || null,
+      background,
+      link: top(links)[0] || null,
+      button,
+      border: top(borders)[0] || null,
+      radius: top(radii)[0] || null,
+    };`);
+  const { button } = raw;
+  return {
+    ok: true,
+    url: printableUrl(raw.url),
+    sampledFrom: "computed styles of visible elements",
+    fontFamily: raw.fontFamily,
+    fontSize: raw.fontSize,
+    text: toHex(raw.text),
+    textMuted: raw.textMuted ? toHex(raw.textMuted) : null,
+    background: toHex(raw.background),
+    link: raw.link ? toHex(raw.link) : null,
+    primaryButton: button
+      ? {
+          background: toHex(button.background),
+          color: toHex(button.color),
+          borderRadius: button.borderRadius,
+          fontWeight: button.fontWeight,
+        }
+      : null,
+    border: raw.border ? toHex(raw.border) : null,
+    boxRadius: raw.radius,
+    body: { ...raw.body, color: toHex(raw.body.color) },
+  };
+}
+
+async function runScreenshot(page, flags) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const file =
+    typeof flags.out === "string"
+      ? path.resolve(flags.out)
+      : path.join(projectDir, ".foldspace-dev", "observe", `${stamp}.png`);
+  await page.screenshot(file);
+  return { ok: true, path: file, url: printableUrl(await page.evaluate("return location.href;")) };
+}
+
+async function runWaitLogin(flags) {
+  const timeoutMs = numberFlag(flags.timeout, 600, "timeout") * 1000;
+  const { hosts } = readLaunchState(projectDir);
+  const started = Date.now();
+  let streak = 0;
+  let url = null;
+  let lastError = null;
+  while (Date.now() - started < timeoutMs) {
+    let page;
+    try {
+      page = await CdpPage.open({ projectDir });
+      const seen = await page.evaluate(
+        `${VISIBLE_JS}
+        return {
+          url: location.href,
+          hasPasswordField: [...document.querySelectorAll("input[type=password]")].some(visible),
+        };`,
+        { timeoutMs: 5000 },
+      );
+      // Post-login URLs carry OAuth codes and the like.
+      url = printableUrl(seen.url);
+      lastError = null;
+      streak = looksLoggedIn({ ...seen, hosts }) ? streak + 1 : 0;
+    } catch (error) {
+      // Mid-navigation, or Chrome not up yet: simply not logged in this poll.
+      streak = 0;
+      lastError = error instanceof Error ? error.message : String(error);
+    } finally {
+      page?.close();
+    }
+    if (streak >= 2) {
+      recordEvent(projectDir, "login_seen", { url });
+      return { ok: true, loggedIn: true, url, waitedMs: Date.now() - started };
+    }
+    await sleep(1500);
+  }
+  throw new ObserveExit({ ok: false, loggedIn: false, url, ...(lastError ? { lastError } : {}) }, 2);
+}
+
+// -------------------------------------------------------------------- main
+
+function splitEquals(argv) {
+  // `--wait=500` and `--wait 500` mean the same thing, as in bin/cli.mjs.
+  return argv.flatMap((token) => {
+    const at = token.indexOf("=");
+    return token.startsWith("--") && at > -1 ? [token.slice(0, at), token.slice(at + 1)] : [token];
+  });
+}
+
+async function main() {
+  const [sub, ...argv] = splitEquals(process.argv.slice(2));
+  const spec = SUBCOMMANDS[sub];
+  if (!spec) {
+    throw new Error(
+      `usage: foldspace observe <${Object.keys(SUBCOMMANDS).join("|")}> [options]` +
+        (sub ? ` (unknown subcommand '${sub}')` : ""),
+    );
+  }
+  const { flags, rest } = parseArgs(argv, spec.values);
+  if (sub === "read") refuseWriteFlags(flags); // before "unknown option": the reason matters
+  const unknown = Object.keys(flags).filter((name) => ![...spec.values, ...spec.flags].includes(name));
+  if (unknown.length) throw new Error(`unknown option '--${unknown[0]}' for observe ${sub}`);
+  for (const name of spec.values) {
+    if (name in flags && (flags[name] === undefined || String(flags[name]).startsWith("--"))) {
+      throw new Error(`option '--${name}' requires a value`);
+    }
+  }
+  if (sub !== "read" && rest.length) throw new Error(`unexpected argument '${rest[0]}'`);
+
+  recordEvent(projectDir, "observe", { sub });
+  if (sub === "pages") return runPages();
+  if (sub === "wait-login") return runWaitLogin(flags);
+
+  const page = await CdpPage.open({ projectDir });
+  try {
+    if (sub === "menu") return await runMenu(page);
+    if (sub === "screen") return await runScreen(page, flags);
+    if (sub === "read") return await runRead(page, flags, rest);
+    if (sub === "auth") return await runAuth(page, flags);
+    if (sub === "styles") return await runStyles(page);
+    return await runScreenshot(page, flags);
+  } finally {
+    page.close();
+  }
+}
+
+try {
+  const document = await main();
+  printJson(document);
+  // `read` follows the HTTP answer so a shell `&&` chain stops on a 401.
+  process.exitCode = document.ok === false ? 1 : 0;
+} catch (error) {
+  if (error instanceof ObserveExit) {
+    printJson(error.document);
+    process.exitCode = error.code;
+  } else {
+    printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+  }
+}
+// A CDP socket that is still closing must not hold the process open.
+setTimeout(() => process.exit(), 50).unref();