stuntdouble 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 Stunt Double Local: run [Stunt Double](https://stuntdouble.io) checklists in a Chrome on your own machine, from your own coding agent session, with every run kept as files in your project and a local viewer to watch and review them.
 
-It is an MCP server and nothing more. Your agent session does all of the reasoning: it reads the actor's brief, drives the browser through the tools here and judges each check. This package drives the browser, checks that a passed verdict cites something on the page, scores the run with the same code as the Stunt Double cloud, and writes the files. It never calls a model, never starts an agent, and never reads an agent's credentials (a test fails the build if it tries), so local runs count against your own plan and nothing else.
+It is an MCP server and nothing more. Your agent session does all of the reasoning: it reads the actor's brief, drives the browser through the tools here and judges each check. This package drives the browser, checks that a passed verdict cites something on the page, scores the run with the same code as the Stunt Double cloud, and writes the files. It never calls a model, never starts an agent, and never reads an agent's credentials (a test fails the build if it tries), so a local run uses whatever account your agent is signed in with, and nothing else.
 
 Most people use it through the Stunt Double plugin for Claude Code, which starts it for you: `/stuntdouble setup`, then `/stuntdouble run <checklist>`.
 
@@ -11,7 +11,7 @@ Most people use it through the Stunt Double plugin for Claude Code, which starts
 ```sh
 npx stuntdouble mcp          # the MCP server over stdio; your agent starts this
 npx stuntdouble view [dir]   # the viewer over a project's .stuntdouble/, no agent needed
-npx stuntdouble doctor       # Node, Chrome, the viewer port, and how local runs are billed
+npx stuntdouble doctor       # Node, Chrome, the viewer port, the project, and how local runs are billed
 ```
 
 To add it to another MCP client, run `npx -y stuntdouble mcp` with `STUNTDOUBLE_PROJECT_DIR` set to the project folder (the current directory otherwise).
@@ -26,7 +26,8 @@ Needs Node 22.18 or later and Google Chrome (or Playwright's Chromium, from `npx
 | `start_run`                                                                                                    | Validates the files (naming every field to fix), opens a fresh Chrome at the checklist's URL and returns the viewer link, the actor's brief and the checks. `resume` continues an interrupted run, or one still open in this session. |
 | `evaluate_check`                                                                                               | Records one verdict. A pass must cite text or a selector that is on the page now. Scrolls the evidence into view and saves `shots/<check>.png`.                                                                                       |
 | `finish_run`                                                                                                   | Settles the checks left, scores the run and closes the browser.                                                                                                                                                                       |
-| `open_ui`                                                                                                      | The viewer's link.                                                                                                                                                                                                                    |
+| `open_ui`                                                                                                      | The viewer's link, and a line on each of the five latest runs: checklist, status, outcome, checks passed and when it started.                                                                                                         |
+| `doctor`                                                                                                       | Read only. The same lines as `npx stuntdouble doctor`, one per check (`ok`, `FAIL`, `note` or `--`), so an agent can run it without a shell. While the viewer runs, it reports the viewer's port rather than probing 4747.            |
 
 ## Files
 
@@ -46,9 +47,11 @@ Actors and checklists use the same fields, and the same limits, as the Stunt Dou
 
 Local results are self-judged: the actor records its own verdicts. Cloud runs add a second judge.
 
+A checklist with no `weighted` checks has no score: it passes only when every pass/fail check passes, and its `pass_threshold`, which applies to weighted checks only, is not used. `start_run` and `finish_run` say so, and the viewer shows the tally with the same sentence.
+
 ## Safety
 
-- Every run gets a fresh Chrome profile, deleted afterwards. An actor with `persist_login` keeps its own profile in `~/.stuntdouble/profiles/<actor>`, never yours.
+- Every run gets a fresh Chrome profile, deleted afterwards. An actor with `persist_login` keeps its own profile in `~/.stuntdouble/profiles/<project>/<actor>` (the project as a short hash of its path, so two projects with the same actor name never share cookies), never yours.
 - The browser reaches local and private addresses only for the app under test: the exact origins (scheme, host and port) of the checklist's URL and `local_base_url`. The rule holds however the browser gets there, by a link, a script, a popup, a frame or a redirect; a redirect's request is still sent, but the page is cleared before any tool reads it.
 - With `safety` at `third_party` (the default), on any other host the tools refuse to pay, subscribe, create an account or type a password or card number. Set it to `off` when your app signs in on another domain.
 - The viewer listens on `127.0.0.1` only (port 4747, or the next free one), answers only to its own Host header, needs the key from the printed link (kept as an HttpOnly, SameSite=Strict cookie), sends no CORS headers and serves files from `.stuntdouble/` only. Its one control is Stop.

package/dist/{chunk-JAB46QV7.js → chunk-7IC2G3Z3.js}

@@ -1,5 +1,13 @@
+// src/ui-server.ts
+import { randomBytes, timingSafeEqual } from "crypto";
+import { watch } from "fs";
+import { readdir as readdir2, readFile as readFile2, realpath } from "fs/promises";
+import { createServer } from "http";
+import { basename, extname, join as join2, resolve, sep as sep2 } from "path";
+
 // src/files.ts
 import { randomUUID } from "crypto";
+import { readFileSync } from "fs";
 import { appendFile, lstat, mkdir, readdir, readFile, rename, writeFile } from "fs/promises";
 import { dirname, join, sep } from "path";
 import { z } from "zod";
@@ -326,7 +334,7 @@ var ActorSchema = z.strictObject({
       content: z.string().min(1).max(ACTOR_KNOWLEDGE_CONTENT_MAX_LENGTH)
     })
   ).default([]),
-  /** Keep this actor's cookies between runs, in ~/.stuntdouble/profiles/<actor>. */
+  /** Keep this actor's cookies between runs, in ~/.stuntdouble/profiles/<project>/<actor>. */
   persist_login: z.boolean().default(false),
   cloud
 });
@@ -397,7 +405,8 @@ var RunSchema = z.object({
   status: z.enum(RUN_STATUSES),
   pid: z.number().optional(),
   url: z.string(),
-  started_at: z.string(),
+  // A run pulled back from the cloud may not have started.
+  started_at: z.string().nullable(),
   finished_at: z.string().nullable(),
   checklist: z.string(),
   actor: z.string(),
@@ -421,8 +430,14 @@ async function readJson(path, schema, label = path) {
   let raw;
   try {
     raw = await readFile(path, "utf8");
-  } catch {
-    throw new Error(`${label}: file not found`);
+  } catch (err) {
+    const code = err.code;
+    throw new Error(
+      `${label}: ${code === "ENOENT" ? "file not found" : `could not read (${code})`}`,
+      {
+        cause: err
+      }
+    );
   }
   let data;
   try {
@@ -465,11 +480,41 @@ function isAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
+  } catch {
+    return false;
+  }
+}
+var runningMarker = (root, id) => join(root, ".live", "running", id);
+function isLive(root, run) {
+  let marker;
+  try {
+    marker = readFileSync(runningMarker(root, run.id), "utf8").trim();
+  } catch {
+    return false;
+  }
+  return marker === String(run.pid) && isAlive(run.pid);
+}
+var effectiveStatus = (root, run) => run.status === "running" && !isLive(root, run) ? "interrupted" : run.status;
+function tallyRun(run) {
+  const status = new Map(run.results.map((r) => [r.check, r.status]));
+  const scored = run.checklist_snapshot.checks.filter(
+    (c) => c.type !== "informational" && status.get(c.key) !== "skipped"
+  );
+  return {
+    passed: scored.filter((c) => status.get(c.key) === "passed").length,
+    total: scored.length
+  };
+}
+async function readRun(root, id) {
+  if (!/^[\w.-]+$/.test(id) || id.startsWith(".")) return null;
+  const path = join(root, "runs", id, "run.json");
+  if (!await lstat(join(root, "runs", id)).catch(() => null)) return null;
+  try {
+    return { id, run: await readJson(path, RunSchema) };
   } catch (err) {
-    return err.code === "EPERM";
+    return { id, error: err.message };
   }
 }
-var effectiveStatus = (run) => run.status === "running" && !isAlive(run.pid) ? "interrupted" : run.status;
 async function readRuns(root) {
   const ids = await readdir(join(root, "runs")).catch(() => []);
   const entries = await Promise.all(
@@ -484,6 +529,246 @@ async function readRuns(root) {
   return entries.sort((a, b) => a.id < b.id ? 1 : -1);
 }
 
+// src/ui-server.ts
+var FIRST_PORT = 4747;
+var PORT_TRIES = 20;
+var TYPES = {
+  ".png": "image/png",
+  ".json": "application/json",
+  ".jsonl": "text/plain; charset=utf-8"
+};
+var PAGE_HEADERS = {
+  "Content-Security-Policy": "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src 'self'; frame-ancestors 'none'; form-action 'none'"
+};
+function send(res, status, body, type = "text/plain; charset=utf-8", headers = {}) {
+  res.writeHead(status, {
+    "Content-Type": type,
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+    "Referrer-Policy": "no-referrer",
+    ...headers
+  });
+  res.end(body);
+}
+var json = (res, data) => send(res, 200, JSON.stringify(data), "application/json");
+function sameSecret(given, token) {
+  const a = Buffer.from(given);
+  const b = Buffer.from(token);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function cookie(req, name) {
+  for (const part of (req.headers.cookie ?? "").split(";")) {
+    const [key, ...value] = part.trim().split("=");
+    if (key === name) return value.join("=");
+  }
+  return void 0;
+}
+async function confined(root, rel) {
+  try {
+    const realRoot = await realpath(root);
+    const real = await realpath(resolve(root, rel));
+    return real.startsWith(realRoot + sep2) ? real : null;
+  } catch {
+    return null;
+  }
+}
+async function definitions(root, folder) {
+  const schema = folder === "checklists" ? ChecklistSchema : ActorSchema;
+  const names = await readdir2(join2(root, folder)).catch(() => []);
+  return Promise.all(
+    names.filter((n) => n.endsWith(".json")).sort().map(async (name) => {
+      const slug2 = basename(name, ".json");
+      try {
+        return { slug: slug2, data: await readJson(join2(root, folder, name), schema, name) };
+      } catch (err) {
+        return { slug: slug2, error: err.message };
+      }
+    })
+  );
+}
+async function actorNames(root) {
+  const actors = await definitions(root, "actors");
+  return new Map(actors.flatMap((a) => "data" in a && a.data ? [[a.slug, a.data.name]] : []));
+}
+function runSummary(root, run, names) {
+  const { checklist_snapshot, results: _results, ...rest } = run;
+  return {
+    ...rest,
+    status: effectiveStatus(root, run),
+    actor_name: names.get(run.actor) ?? null,
+    checklist_name: typeof checklist_snapshot.name === "string" ? checklist_snapshot.name : null,
+    tally: tallyRun(run)
+  };
+}
+async function readBody(req) {
+  let body = "";
+  for await (const chunk of req) {
+    body += chunk;
+    if (body.length > 1e4) throw new Error("Body too large");
+  }
+  return body;
+}
+async function startUi(options) {
+  const root = resolve(options.root);
+  const token = randomBytes(24).toString("base64url");
+  const clients = /* @__PURE__ */ new Set();
+  let port = 0;
+  async function handle(req, res) {
+    const host = req.headers.host ?? "";
+    if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+      return send(res, 403, "Forbidden");
+    }
+    const url = new URL(req.url ?? "/", `http://${host}`);
+    if (url.pathname === "/__stuntdouble") return json(res, { stuntdouble: true });
+    if (url.pathname === "/favicon.ico") return send(res, 204, "");
+    const cookieName = `stuntdouble_${port}`;
+    const key = url.searchParams.get("t");
+    if (key !== null) {
+      if (!sameSecret(key, token)) return send(res, 403, "This link is out of date.");
+      url.searchParams.delete("t");
+      return send(res, 302, "", void 0, {
+        Location: `${url.pathname}${url.search}`,
+        "Set-Cookie": `${cookieName}=${token}; HttpOnly; SameSite=Strict; Path=/`
+      });
+    }
+    const signedIn = cookie(req, cookieName);
+    if (!signedIn || !sameSecret(signedIn, token)) {
+      return send(
+        res,
+        403,
+        "Open the viewer from the link Stunt Double printed: it carries the key."
+      );
+    }
+    const path = url.pathname;
+    if (req.method === "POST" && path === "/api/stop") {
+      const origin = req.headers.origin;
+      if (origin && origin !== `http://${host}`) return send(res, 403, "Forbidden");
+      const { run } = JSON.parse(await readBody(req));
+      const entry = typeof run === "string" ? await readRun(root, run) : null;
+      if (!entry || !("run" in entry) || effectiveStatus(root, entry.run) !== "running") {
+        return send(res, 409, "That run is not going.");
+      }
+      await writeFileAtomic(join2(root, ".live", "stop"), entry.id);
+      return send(res, 204, "");
+    }
+    if (req.method !== "GET") return send(res, 405, "Method not allowed");
+    if (path === "/" || path === "/definitions" || /^\/runs\/[^/]+$/.test(path)) {
+      const page = await readFile2(new URL("./ui.html", import.meta.url));
+      return send(res, 200, page, "text/html; charset=utf-8", PAGE_HEADERS);
+    }
+    if (path === "/api/runs") {
+      const [runs, names] = await Promise.all([readRuns(root), actorNames(root)]);
+      return json(
+        res,
+        runs.map((e) => "run" in e ? runSummary(root, e.run, names) : e)
+      );
+    }
+    const runMatch = path.match(/^\/api\/runs\/([^/]+)$/);
+    if (runMatch) {
+      const id = decodeURIComponent(runMatch[1]);
+      const entry = await readRun(root, id);
+      if (!entry) return send(res, 404, "No such run");
+      const activity = await readFile2(join2(root, "runs", entry.id, "activity.jsonl"), "utf8").then(
+        (text) => text.split("\n").filter(Boolean).map((line) => JSON.parse(line))
+      ).catch(() => []);
+      const stop = await readFile2(join2(root, ".live", "stop"), "utf8").catch(() => "");
+      const names = "run" in entry ? await actorNames(root) : /* @__PURE__ */ new Map();
+      return json(res, {
+        ...entry,
+        ..."run" in entry ? {
+          run: {
+            ...entry.run,
+            status: effectiveStatus(root, entry.run),
+            actor_name: names.get(entry.run.actor) ?? null
+          }
+        } : {},
+        activity,
+        stop_requested: stop.trim() === entry.id
+      });
+    }
+    if (path === "/api/definitions") {
+      return json(res, {
+        checklists: await definitions(root, "checklists"),
+        actors: await definitions(root, "actors")
+      });
+    }
+    if (path === "/api/events") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff"
+      });
+      res.write(": connected\n\n");
+      clients.add(res);
+      req.on("close", () => clients.delete(res));
+      return;
+    }
+    if (path.startsWith("/files/")) {
+      const rel = decodeURIComponent(path.slice("/files/".length));
+      const file = await confined(root, rel);
+      if (!file) return send(res, 403, "Outside .stuntdouble/");
+      const type = TYPES[extname(file)];
+      if (!type) return send(res, 404, "Not found");
+      const cache = rel.includes("/shots/") ? "private, max-age=86400" : "no-store";
+      return send(res, 200, await readFile2(file), type, { "Cache-Control": cache });
+    }
+    return send(res, 404, "Not found");
+  }
+  const server = createServer((req, res) => {
+    handle(req, res).catch(() => {
+      if (res.headersSent) res.end();
+      else send(res, 500, "Something went wrong reading .stuntdouble/");
+    });
+  });
+  const first = options.port ?? FIRST_PORT;
+  for (let candidate = first; ; candidate++) {
+    try {
+      await new Promise((ok, fail) => {
+        server.once("error", fail);
+        server.listen(candidate, "127.0.0.1", () => {
+          server.off("error", fail);
+          ok();
+        });
+      });
+      break;
+    } catch (err) {
+      const busy = err.code === "EADDRINUSE";
+      if (!busy || candidate >= first + PORT_TRIES) throw err;
+    }
+  }
+  port = server.address().port;
+  let watcher = null;
+  let pending = /* @__PURE__ */ new Set();
+  let timer;
+  try {
+    watcher = watch(root, { recursive: true }, (_event, name) => {
+      if (!name || name.endsWith(".tmp")) return;
+      pending.add(String(name).split(sep2).join("/"));
+      timer ??= setTimeout(() => {
+        const data = `data: ${JSON.stringify({ paths: [...pending] })}
+
+`;
+        for (const client of clients) client.write(data);
+        pending = /* @__PURE__ */ new Set();
+        timer = void 0;
+      }, 150);
+    });
+  } catch {
+  }
+  return {
+    port,
+    token,
+    link: (path = "/") => `http://127.0.0.1:${port}${path}?t=${token}`,
+    close: async () => {
+      watcher?.close();
+      clearTimeout(timer);
+      for (const client of clients) client.end();
+      server.closeAllConnections();
+      await new Promise((ok) => server.close(() => ok()));
+    }
+  };
+}
+
 export {
   resolveSkippedChecks,
   resolveHaltedChecks,
@@ -499,8 +784,12 @@ export {
   writeJsonAtomic,
   writeFileAtomic,
   appendJsonl,
-  isAlive,
+  runningMarker,
+  isLive,
   effectiveStatus,
-  readRuns
+  tallyRun,
+  readRuns,
+  FIRST_PORT,
+  startUi
 };
-//# sourceMappingURL=chunk-JAB46QV7.js.map
+//# sourceMappingURL=chunk-7IC2G3Z3.js.map