muse-crew 0.7.9 → 0.7.11

package/lib/see-act.js

@@ -0,0 +1,327 @@
+// see-act.js — single-step browser driver for experiential QA.
+//
+// The agent closes the OODA loop: run one step, READ the screenshot or aria
+// output, decide the next step. Each invocation launches a fresh browser,
+// performs exactly one action, prints one JSON line to stdout, and exits.
+//
+// Self-contained: spawns its own loopback forward proxy on an ephemeral port
+// (Chromium's Local Network Access checks block direct loopback navigation),
+// so the caller needs no proxy infrastructure.
+//
+// Usage:
+//   node see-act.js --url <url> [--viewport desktop|mobile] [--timeout-ms <n>] <action> [args]
+//
+// Actions:
+//   aria                                   print interactive elements as JSON
+//   shot   --out <png> [--full]              screenshot the viewport (or full page) to <png>
+//   click  --out <png> --selector <css>     click, then screenshot to <png>
+//   scroll --out <png> --y <px|bottom>      scroll window, then screenshot
+//   type   --out <png> --selector <css> --text <text>
+//
+// Archival: when SEE_ACT_ARCHIVE_DIR is set, every screenshot is also saved
+// there as <NNN>-<action>-<viewport>.png (sequential, zero-padded) and the
+// JSON reports it. --out becomes optional: omit it and the screenshot goes
+// straight to the archive. This funnels every captured image through one
+// evidence dir no matter which phase (QA, repro, hunt) took it, so the agent
+// cannot forget to save a frame.
+//
+// Exit codes: 0 = ok, 2 = usage/action error, 3 = NOT POSSIBLE (environment).
+// Stdout is always one JSON object: {ok:true,...} or {ok:false,error|not_possible}.
+// Determinism: no wall-clock reads, no randomness. Archive names are sequential.
+//
+// Dependencies: playwright-core (resolved below), a Chromium binary.
+"use strict";
+
+const { createServer, request: httpRequest } = require("node:http");
+const { request: httpsRequest } = require("node:https");
+const { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } = require("node:fs");
+const { join, dirname, resolve } = require("node:path");
+
+const VIEWPORTS = {
+  desktop: { width: 1440, height: 900 },
+  mobile: { width: 390, height: 844 },
+};
+const DEFAULT_TIMEOUT_MS = 30000;
+const SETTLE_MS = 1500;
+
+function fail(code, obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const out = { action: null, url: null, viewport: "desktop", timeoutMs: DEFAULT_TIMEOUT_MS };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--viewport") out.viewport = argv[++i];
+    else if (a === "--timeout-ms") out.timeoutMs = parseInt(argv[++i], 10);
+    else if (a === "--out") out.out = argv[++i];
+    else if (a === "--selector") out.selector = argv[++i];
+    else if (a === "--y") out.y = argv[++i];
+    else if (a === "--text") out.text = argv[++i];
+    else if (a === "--full") out.full = true;
+    else if (!a.startsWith("--") && out.action === null) out.action = a;
+    else rest.push(a);
+  }
+  out.extra = rest;
+  return out;
+}
+
+function loadPlaywright() {
+  try {
+    return require("playwright-core");
+  } catch (e) { /* fall through */ }
+  const envDir = (process.env.PLAYWRIGHT_CORE_DIR || "").trim();
+  if (envDir) {
+    try {
+      return require(join(envDir, "playwright-core"));
+    } catch (e) { /* fall through */ }
+    try {
+      return require(envDir);
+    } catch (e) { /* fall through */ }
+  }
+  const conventional = "/home/hatch/workspace/crew-tools/node_modules/playwright-core";
+  if (existsSync(conventional)) {
+    try {
+      return require(conventional);
+    } catch (e) { /* fall through */ }
+  }
+  fail(3, {
+    ok: false,
+    not_possible: "NOT POSSIBLE: playwright-core is not installed or not resolvable. " +
+      "Install it (npm install playwright-core) or set PLAYWRIGHT_CORE_DIR.",
+  });
+}
+
+function findChromium() {
+  const envPath = (process.env.CHROME_PATH || "").trim();
+  if (envPath && existsSync(envPath)) return envPath;
+  const sysPath = "/opt/meta-chromium/chrome";
+  if (existsSync(sysPath)) return sysPath;
+  fail(3, {
+    ok: false,
+    not_possible: "NOT POSSIBLE: no Chromium binary found. " +
+      "Set CHROME_PATH to a Chromium/Chrome executable.",
+  });
+}
+
+// Archive dir: every screenshot is funneled here when SEE_ACT_ARCHIVE_DIR is
+// set, regardless of phase. Returns the dir, or null when not archiving.
+// A missing dir is created; an unusable dir is NOT POSSIBLE (exit 3) — lost
+// evidence must fail loudly, never silently.
+function resolveArchiveDir() {
+  const d = (process.env.SEE_ACT_ARCHIVE_DIR || "").trim();
+  if (!d) return null;
+  const abs = resolve(d);
+  try {
+    mkdirSync(abs, { recursive: true });
+  } catch (e) {
+    fail(3, {
+      ok: false,
+      not_possible: "NOT POSSIBLE: cannot create archive dir " + abs + ": " + ((e && e.message) || String(e)),
+    });
+  }
+  return abs;
+}
+
+// Next sequential archive path. The counter lives in <dir>/.seq so names are
+// stable across the driver's one-process-per-invocation shape. No wall-clock,
+// no randomness — purely sequential.
+function nextArchivePath(dir, action, viewport) {
+  const seqFile = join(dir, ".seq");
+  let n = 0;
+  try {
+    const raw = readFileSync(seqFile, "utf8").trim();
+    const parsed = parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed >= 0) n = parsed;
+  } catch (e) { /* first capture */ }
+  n += 1;
+  try {
+    writeFileSync(seqFile, String(n) + "\n");
+  } catch (e) {
+    fail(3, {
+      ok: false,
+      not_possible: "NOT POSSIBLE: archive dir not writable: " + dir,
+    });
+  }
+  return join(dir, String(n).padStart(3, "0") + "-" + action + "-" + viewport + ".png");
+}
+
+// Minimal forward proxy: Chromium -> proxy (loopback, allowed) -> target
+// (loopback, made by us so the Local Network Access check never fires).
+function startProxy() {
+  return new Promise((resolve, reject) => {
+    const server = createServer((clientReq, clientRes) => {
+      let url;
+      try {
+        url = new URL(clientReq.url);
+      } catch {
+        clientRes.writeHead(400);
+        clientRes.end("bad url");
+        return;
+      }
+      const lib = url.protocol === "https:" ? httpsRequest : httpRequest;
+      const headers = Object.assign({}, clientReq.headers);
+      headers.host = url.host;
+      const proxyReq = lib(
+        {
+          hostname: url.hostname,
+          port: url.port || (url.protocol === "https:" ? 443 : 80),
+          path: url.pathname + url.search,
+          method: clientReq.method,
+          headers: headers,
+        },
+        (proxyRes) => {
+          clientRes.writeHead(proxyRes.statusCode, proxyRes.headers);
+          proxyRes.pipe(clientRes);
+        }
+      );
+      proxyReq.on("error", (e) => {
+        clientRes.writeHead(502);
+        clientRes.end("proxy error: " + e.message);
+      });
+      clientReq.pipe(proxyReq);
+    });
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      resolve({ server: server, port: server.address().port });
+    });
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.url) {
+    fail(2, { ok: false, error: "usage: node see-act.js --url <url> [--viewport desktop|mobile] <aria|shot|click|scroll|type> [args]" });
+  }
+  if (!VIEWPORTS[args.viewport]) {
+    fail(2, { ok: false, error: "unknown viewport: " + args.viewport + " (desktop|mobile)" });
+  }
+  const validActions = { aria: 1, shot: 1, click: 1, scroll: 1, type: 1 };
+  if (!validActions[args.action]) {
+    fail(2, { ok: false, error: "unknown action: " + args.action + " (aria|shot|click|scroll|type)" });
+  }
+  const needsShot = args.action !== "aria";
+  if (needsShot && !args.out && !process.env.SEE_ACT_ARCHIVE_DIR) {
+    fail(2, { ok: false, error: "action " + args.action + " requires --out <png> (or set SEE_ACT_ARCHIVE_DIR to archive automatically)" });
+  }
+  if (args.action === "click" && !args.selector) {
+    fail(2, { ok: false, error: "click requires --selector <css>" });
+  }
+  if (args.action === "type" && (!args.selector || args.text === undefined)) {
+    fail(2, { ok: false, error: "type requires --selector <css> --text <text>" });
+  }
+
+  const { chromium } = loadPlaywright();
+  const exePath = findChromium();
+  const proxy = await startProxy();
+
+  // Archival is resolved before the browser launches so an unusable dir
+  // fails fast (exit 3) instead of wasting a browser session.
+  const archiveDir = resolveArchiveDir();
+  const archivePath = (archiveDir && needsShot) ? nextArchivePath(archiveDir, args.action, args.viewport) : null;
+
+  const result = { ok: true, action: args.action, viewport: args.viewport };
+
+  // Capture helper: screenshot to the primary destination, then funnel a
+  // copy into the archive when one is configured. result.screenshot is the
+  // single path the agent should read.
+  async function capture(page, opts) {
+    const dest = args.out || archivePath;
+    await page.screenshot(Object.assign({ path: dest }, opts));
+    if (args.out) result.out = args.out;
+    result.screenshot = dest;
+    if (archivePath && resolve(dest) !== archivePath) {
+      copyFileSync(dest, archivePath);
+      result.archived = archivePath;
+    } else if (archivePath) {
+      result.archived = archivePath;
+    }
+  }
+
+  let browser = null;
+  try {
+    browser = await chromium.launch({
+      executablePath: exePath,
+      args: ["--no-sandbox"],
+      proxy: { server: "http://127.0.0.1:" + proxy.port },
+    });
+    const page = await browser.newPage({ viewport: VIEWPORTS[args.viewport] });
+    const consoleErrors = [];
+    page.on("console", (msg) => {
+      if (msg.type() === "error") consoleErrors.push(msg.text().slice(0, 300));
+    });
+    page.on("pageerror", (err) => {
+      consoleErrors.push(String((err && err.message) || err).slice(0, 300));
+    });
+
+    await page.goto(args.url, { waitUntil: "domcontentloaded", timeout: args.timeoutMs });
+    await page.waitForLoadState("networkidle", { timeout: 15000 }).catch(() => {});
+    await page.waitForTimeout(SETTLE_MS);
+
+    if (args.action === "aria") {
+      const els = await page.evaluate(() => {
+        const out = [];
+        document.querySelectorAll("button, a, [role=button], [role=tab], input, select, textarea, h1, h2").forEach((el) => {
+          const t = (el.innerText || el.value || el.getAttribute("aria-label") || "").trim().slice(0, 80).replace(/\s+/g, " ");
+          if (t) out.push(el.tagName.toLowerCase() + ": " + t);
+        });
+        document.querySelectorAll("footer").forEach((el) => {
+          const t = (el.innerText || "").trim().slice(0, 300).replace(/\s+/g, " ");
+          if (t) out.push("footer: " + t);
+        });
+        return out.slice(0, 60);
+      });
+      result.aria = els;
+    } else if (args.action === "shot") {
+      await capture(page, { fullPage: !!args.full });
+      result.full_page = !!args.full;
+    } else if (args.action === "click") {
+      await page.click(args.selector, { timeout: args.timeoutMs });
+      await page.waitForTimeout(SETTLE_MS);
+      await capture(page, {});
+      result.selector = args.selector;
+    } else if (args.action === "scroll") {
+      const y = args.y === undefined || args.y === "bottom" ? "bottom" : String(parseInt(args.y, 10));
+      await page.evaluate((yy) => {
+        const wantBottom = yy === "bottom";
+        const px = wantBottom ? 0 : parseInt(yy, 10);
+        // Scroll the real scroller: the body, or the tallest scrollable
+        // container when the body itself does not scroll (app shells).
+        let el = document.scrollingElement || document.body;
+        if (el.scrollHeight <= el.clientHeight + 1) {
+          let best = null, bestH = 0;
+          document.querySelectorAll("*").forEach((e) => {
+            if (e.scrollHeight > e.clientHeight + 50 && e.scrollHeight > bestH) { best = e; bestH = e.scrollHeight; }
+          });
+          if (best) el = best;
+        }
+        el.scrollTo(0, wantBottom ? el.scrollHeight : px);
+      }, y);
+      await page.waitForTimeout(1000);
+      await capture(page, {});
+      result.y = y;
+    } else if (args.action === "type") {
+      await page.fill(args.selector, args.text, { timeout: args.timeoutMs });
+      await page.waitForTimeout(800);
+      await capture(page, {});
+      result.selector = args.selector;
+    }
+    result.console_errors = consoleErrors.slice(0, 10);
+    result.console_error_count = consoleErrors.length;
+  } catch (e) {
+    await browser.close().catch(() => {});
+    proxy.server.close();
+    fail(2, { ok: false, error: "action failed: " + ((e && e.message) || String(e)).slice(0, 500) });
+  }
+  await browser.close().catch(() => {});
+  proxy.server.close();
+  process.stdout.write(JSON.stringify(result) + "\n");
+  process.exit(0);
+}
+
+main().catch((e) => {
+  fail(2, { ok: false, error: "driver error: " + ((e && e.message) || String(e)).slice(0, 500) });
+});

package/lib/serve-artifact.js

@@ -0,0 +1,203 @@
+// serve-artifact.js — serve a built TS space locally for experiential QA.
+//
+// Serves <space-dir>/client/dist statically and dispatches POST */actions
+// {action, args} to the compiled server actions with a locally-built Ctx,
+// so a QA agent can drive the artifact in a real browser exactly as the
+// shipped server code behaves. Read-only w.r.t. the space directory: never
+// writes into it.
+//
+// Usage:
+//   node serve-artifact.js --space-dir <path> [--port <n>]
+// Prints "READY port=<n>" on stdout, then serves until killed.
+// --port 0 (default) picks an ephemeral port.
+//
+// Fidelity notes (what this is and isn't):
+// - The served client and action handlers are the artifact's own built code.
+// - The Ctx is locally built: privileged handlers run from the space's own
+//   server/dist/privileged.js when present; blobs are stored in a per-run
+//   temp dir and served back at /__blobs/<key>.
+// - Environment (CREW_HOME and friends) is inherited from the caller — export
+//   what the artifact's server needs before starting this.
+//
+// Determinism: no wall-clock reads, no randomness.
+"use strict";
+
+const { createServer } = require("node:http");
+const { join, normalize, dirname, sep } = require("node:path");
+const { existsSync } = require("node:fs");
+const { readFile, writeFile, mkdir, mkdtemp } = require("node:fs/promises");
+const { tmpdir } = require("node:os");
+
+function parseArgs(argv) {
+  const out = { spaceDir: null, port: 0, tag: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--space-dir") out.spaceDir = argv[++i];
+    else if (argv[i] === "--port") out.port = parseInt(argv[++i], 10);
+    else if (argv[i] === "--tag") out.tag = argv[++i];
+  }
+  return out;
+}
+
+function failNotPossible(reason) {
+  process.stdout.write(JSON.stringify({ ok: false, not_possible: "NOT POSSIBLE: " + reason }) + "\n");
+  process.exit(3);
+}
+
+const CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ttf": "font/ttf",
+};
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.spaceDir) {
+    process.stderr.write("serve-artifact.js: --space-dir <path> is required\n");
+    process.exit(2);
+  }
+  if (!existsSync(args.spaceDir)) {
+    failNotPossible("no built artifact at " + args.spaceDir + " (deploy slug has no local build)");
+  }
+  const DIST = join(args.spaceDir, "client", "dist");
+  const ACTIONS_PATH = join(args.spaceDir, "server", "dist", "actions.js");
+  const PRIV_PATH = join(args.spaceDir, "server", "dist", "privileged.js");
+  if (!existsSync(DIST) || !existsSync(ACTIONS_PATH)) {
+    failNotPossible(args.spaceDir + " is not a built TS space (need client/dist and server/dist/actions.js)");
+  }
+
+  const { Actions } = await import(ACTIONS_PATH);
+  let privilegedByName = new Map();
+  if (existsSync(PRIV_PATH)) {
+    const { privilegedHandlers } = await import(PRIV_PATH);
+    privilegedByName = new Map(privilegedHandlers.entries.map((e) => [e.contract.name, e.handler]));
+  }
+
+  // Local blob store (outside the space dir — the server stays read-only
+  // w.r.t. the space). Keys are path-safe segments; anything else is rejected.
+  const BLOB_DIR = await mkdtemp(join(tmpdir(), "serve-artifact-blobs-"));
+  function safeBlobPath(key) {
+    if (typeof key !== "string" || !key || key.includes("..")) return null;
+    const parts = key.split("/").filter((s) => s && s !== "." && s !== "..");
+    if (parts.length === 0 || parts.some((s) => s.includes(sep))) return null;
+    const p = normalize(join(BLOB_DIR, ...parts));
+    if (!p.startsWith(BLOB_DIR + sep)) return null;
+    return p;
+  }
+
+  function makeCtx(def) {
+    const declared = new Set(((def && def.privileged) || []).map((c) => c.name));
+    return {
+      async executePrivileged(contract, actionArgs) {
+        if (!contract || typeof contract.name !== "string") throw new Error("executePrivileged: bad contract descriptor");
+        if (!declared.has(contract.name)) throw new Error("executePrivileged(" + contract.name + ") was not declared by this action");
+        const handler = privilegedByName.get(contract.name);
+        if (!handler) throw new Error("no privileged handler: " + contract.name);
+        const parsed = contract.request.parse(actionArgs);
+        const result = await handler(parsed);
+        return contract.response.parse(result);
+      },
+      invalidateQueries() {},
+      blobs: {
+        async head(key) {
+          const p = safeBlobPath(key);
+          if (!p || !existsSync(p)) return null;
+          return { key: key };
+        },
+        async put(key, bytes, opts) {
+          const p = safeBlobPath(key);
+          if (!p) throw new Error("blobs.put: invalid key");
+          await mkdir(dirname(p), { recursive: true });
+          await writeFile(p, Buffer.from(bytes));
+          return { key: key };
+        },
+        async getUrl(key) {
+          return "/__blobs/" + key.split("/").map(encodeURIComponent).join("/");
+        },
+      },
+    };
+  }
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, "http://local");
+    if (req.method === "GET" && url.pathname.startsWith("/__blobs/")) {
+      const key = url.pathname.slice("/__blobs/".length).split("/").map(decodeURIComponent).join("/");
+      const p = safeBlobPath(key);
+      if (!p || !existsSync(p)) {
+        res.writeHead(404);
+        res.end("not found");
+        return;
+      }
+      try {
+        const data = await readFile(p);
+        const ext = p.slice(p.lastIndexOf("."));
+        res.writeHead(200, { "content-type": CONTENT_TYPES[ext] || "application/octet-stream" });
+        res.end(data);
+      } catch {
+        res.writeHead(404);
+        res.end("not found");
+      }
+      return;
+    }
+    if (req.method === "POST" && url.pathname.endsWith("/actions")) {
+      let body;
+      try {
+        const chunks = [];
+        for await (const chunk of req) chunks.push(chunk);
+        body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      } catch {
+        res.writeHead(400, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "bad json" }));
+        return;
+      }
+      const def = Actions[body.action];
+      if (!def) {
+        res.writeHead(404, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "unknown action: " + body.action }));
+        return;
+      }
+      try {
+        const parsedArgs = def.request.parse(body.args || {});
+        const result = await def.handler(makeCtx(def), parsedArgs);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ data: def.response.parse(result) }));
+      } catch (err) {
+        process.stderr.write("action 500: " + body.action + " :: " + String((err && err.message) || err).slice(0, 300) + "\n");
+        res.writeHead(500, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: String((err && err.message) || err) }));
+      }
+      return;
+    }
+    let p = normalize(join(DIST, url.pathname === "/" ? "index.html" : url.pathname.slice(1)));
+    if (!p.startsWith(DIST)) {
+      res.writeHead(403);
+      res.end("forbidden");
+      return;
+    }
+    if (!existsSync(p)) p = join(DIST, "index.html");
+    const ext = p.slice(p.lastIndexOf("."));
+    try {
+      const data = await readFile(p);
+      res.writeHead(200, { "content-type": CONTENT_TYPES[ext] || "application/octet-stream" });
+      res.end(data);
+    } catch {
+      res.writeHead(404);
+      res.end("not found");
+    }
+  });
+
+  server.listen(args.port, "127.0.0.1", () => {
+    process.stdout.write("READY port=" + server.address().port + "\n");
+  });
+}
+
+main().catch((e) => {
+  process.stderr.write("serve-artifact.js: " + ((e && e.message) || String(e)) + "\n");
+  process.exit(2);
+});