playthrough 0.4.2 → 0.4.3

package/README.md

@@ -4,6 +4,8 @@ The agent says it's done. You decide if it's good.
 
 Playthrough records your coding agent's change the way a person would use it, before and after, so you can watch it instead of setting it up by hand. Point at what's wrong, right on the recording, and the next round answers it there. Take over any moment and carry on in the real app. It runs on your machine, with any coding agent that has a shell.
 
+To see a review before you install anything, play the one at [playthrough.sh](https://playthrough.sh).
+
 ## Try it
 
 Ask your agent for a change in your app, as you would anyway, and add:

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "playthrough",
-  "version": "0.4.2",
-  "description": "Review an AI agent's work on a web app by watching recordings of it.",
+  "version": "0.4.3",
+  "description": "Review what your coding agent built in your web app by watching recordings of it.",
+  "keywords": [
+    "coding-agent",
+    "claude-code",
+    "cursor",
+    "codex",
+    "ai-agents",
+    "code-review",
+    "ui-review",
+    "playwright",
+    "recording",
+    "human-in-the-loop",
+    "developer-tools",
+    "web-app"
+  ],
+  "homepage": "https://playthrough.sh",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {

package/src/playthrough.js

@@ -6,7 +6,7 @@ import { createRequire } from "node:module";
 import { copyFileSync, cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { constants, networkInterfaces, tmpdir, userInfo } from "node:os";
 import { dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { chromium, request } from "@playwright/test";
@@ -557,14 +557,17 @@ async function takeOver$1(repo, id, flowName, stepName) {
 		throw new Refused([`Take over which flow? playthrough take-over ${id} "<flow>" ["<step>"]\nIts flows: ${list(round.flows.map((flow) => quote(flow.name)))}.`]);
 	}
 	console.log(`Running ${quote(flowName)} to ${stepName ? `the end of ${quote(stepName)}` : "its end"}, on the app as it is now…`);
-	const { port, moment, seconds } = await getReady(repo, id, flowName, { step: stepName });
+	const { port, moment, seconds } = await getReady(repo, id, flowName, {
+		step: stepName,
+		network: true
+	});
 	const here = `http://localhost:${port}/take-over/${moment}`;
 	const away = addresses().map((address) => `http://${address}:${port}/take-over/${moment}`);
 	console.log(`
 Ready in ${seconds}s. Carry on from there in your browser: ${here}${away.length ? `\nOr on your phone, on the same network: ${list(away)}` : ""}
 Each address hands over the same copy, and the app is passed on through Playthrough while this runs. Ctrl+C ends it.`);
 }
-async function getReady(repo, id, flowName, { step: stepName, actions, did, ahead } = {}) {
+async function getReady(repo, id, flowName, { step: stepName, actions, did, ahead, network } = {}) {
 	const round = await recorded(repo, id);
 	const flow = round.flows.find((flow) => flow.name === flowName);
 	if (!flow) throw new Refused([`${id} has no flow called ${quote(flowName)}. Its flows: ${list(round.flows.map((flow) => quote(flow.name)))}.`]);
@@ -584,10 +587,9 @@ async function getReady(repo, id, flowName, { step: stepName, actions, did, ahea
 	});
 	passing ??= {
 		moments: /* @__PURE__ */ new Map(),
-		port: passOn(app, (moment) => passing.moments.get(moment)),
-		numbered: 0
+		port: passOn(app, (moment) => passing.moments.get(moment), network)
 	};
-	const moment = String(++passing.numbered);
+	const moment = randomBytes(12).toString("base64url");
 	passing.moments.set(moment, did?.length ? {
 		...handed,
 		did
@@ -625,11 +627,13 @@ async function recorded(repo, id) {
 	if (!round) throw new Refused([`${id} has nothing recorded yet, so there's nothing to take over. Record it first: playthrough record ${id}`]);
 	return round;
 }
-function passOn(app, handed) {
+function passOn(app, handed, network) {
 	const target = new URL(app.url);
 	const server = createServer((request, response) => {
+		if (!named(request)) return turnAway(response);
 		const [first, moment] = new URL(request.url ?? "/", "http://playthrough").pathname.split("/").filter(Boolean);
-		if (first === "take-over") return handOver(handed(moment ?? ""), response);
+		if (first === "take-over") return handOver(handed(moment ?? ""), response, !fromThisMachine(request));
+		if (!passed(request)) return turnAway(response);
 		const page = /text\/html/.test(request.headers.accept ?? "");
 		const headers = asIfDirect(request, target);
 		if (page) delete headers["accept-encoding"];
@@ -640,7 +644,7 @@ function passOn(app, handed) {
 			path: request.url,
 			headers
 		}, (answer) => {
-			const told = fromTheApp(answer, target);
+			const told = fromTheApp(answer, target, request);
 			if (!page || !/text\/html/.test(String(answer.headers["content-type"])) || answer.headers["content-encoding"]) {
 				response.writeHead(answer.statusCode ?? 502, told);
 				answer.pipe(response);
@@ -662,6 +666,7 @@ function passOn(app, handed) {
 		request.pipe(forward);
 	});
 	server.on("upgrade", (request, socket, head) => {
+		if (!named(request) || !passed(request)) return void socket.destroy();
 		const upstream = connect(Number(target.port || 80), target.hostname, () => {
 			const headers = Object.entries(asIfDirect(request, target)).flatMap(([name, value]) => [value ?? []].flat().map((one) => `${name}: ${one}`));
 			upstream.write(`${request.method} ${request.url} HTTP/1.1\r\n${headers.join("\r\n")}\r\n\r\n`);
@@ -671,7 +676,15 @@ function passOn(app, handed) {
 		upstream.on("error", () => socket.destroy());
 		socket.on("error", () => upstream.destroy());
 	});
-	return listen(server, PORT$1, "0.0.0.0");
+	return listen(server, PORT$1, network ? "0.0.0.0" : "127.0.0.1");
+}
+const named = (request) => thisMachine(request.headers.host) || addresses().includes(request.headers.host?.replace(/:\d+$/, "") ?? "");
+const PASS = `playthrough-pass=${randomBytes(16).toString("base64url")}`;
+const fromThisMachine = (request) => /^(127\.|::1$|::ffff:127\.)/.test(request.socket.remoteAddress ?? "");
+const passed = (request) => fromThisMachine(request) || !!request.headers.cookie?.split(/;\s*/).includes(PASS);
+function turnAway(response) {
+	response.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+	response.end("Playthrough passes the app on to this machine, and to whoever opened the address of a moment taken over. Open that address first.");
 }
 function asIfDirect(request, target) {
 	const headers = {
@@ -681,6 +694,9 @@ function asIfDirect(request, target) {
 	const from = `http://${request.headers.host}`;
 	if (headers.origin) headers.origin = target.origin;
 	if (headers.referer?.startsWith(from)) headers.referer = target.origin + headers.referer.slice(from.length);
+	const cookie = headers.cookie?.split(/;\s*/).filter((one) => one !== PASS).join("; ");
+	if (cookie) headers.cookie = cookie;
+	else delete headers.cookie;
 	return headers;
 }
 const recorder = join(dirname(createRequire(import.meta.url).resolve("@rrweb/record")), "record.umd.min.cjs");
@@ -1023,17 +1039,19 @@ const SAYS = `<script>(() => {
   };
   addEventListener("load", () => setTimeout(settle, 50));
 })();<\/script>`;
-function fromTheApp(answer, target) {
+function fromTheApp(answer, target, request) {
 	const headers = { ...answer.headers };
 	delete headers["x-frame-options"];
-	headers["access-control-allow-origin"] = "*";
+	const origin = request.headers.origin;
+	if (origin && URL.canParse(origin) && thisMachine(new URL(origin).host)) headers["access-control-allow-origin"] = origin;
+	headers.vary = [headers.vary, "Origin"].filter(Boolean).join(", ");
 	const policy = headers["content-security-policy"];
 	if (policy) headers["content-security-policy"] = [policy].flat().map((rule) => rule.replace(/frame-ancestors[^;]*;?/i, ""));
 	if (headers.location?.startsWith(target.origin)) headers.location = headers.location.slice(target.origin.length) || "/";
 	if (headers["set-cookie"]) headers["set-cookie"] = headers["set-cookie"].map((cookie) => cookie.replace(/;\s*Domain=[^;]*/i, ""));
 	return headers;
 }
-function handOver(handed, response) {
+function handOver(handed, response, elsewhere) {
 	if (!handed) {
 		response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
 		response.end("There's no moment ready at this address. Take it over again from the viewer, or with playthrough take-over.");
@@ -1043,6 +1061,7 @@ function handOver(handed, response) {
 	const again = handed.again ?? [];
 	const { pathname, search, hash } = new URL(url);
 	const setCookies = cookies.map(({ name, value, path, expires, httpOnly }) => `${name}=${value}; Path=${path}; SameSite=Lax${httpOnly ? "; HttpOnly" : ""}${expires > 0 ? `; Expires=${(/* @__PURE__ */ new Date(expires * 1e3)).toUTCString()}` : ""}`);
+	if (elsewhere) setCookies.push(`${PASS}; Path=/; SameSite=Lax; HttpOnly`);
 	const keep = JSON.stringify({
 		local,
 		session,
@@ -1112,6 +1131,8 @@ async function open(repo, id) {
 	console.log(`Playthrough is open at http://localhost:${port}/${id ?? ""}`);
 }
 async function answer(repo, page, you, request, response) {
+	const stranger = fromElsewhere(request);
+	if (stranger) return json(response, 403, { problems: [stranger] });
 	const reviews = repo.reviews;
 	const path = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname);
 	const [api, collection, id, ...rest] = path.split("/").filter(Boolean);
@@ -1244,6 +1265,12 @@ async function serve(page, path, response) {
 	});
 	response.end(await readFile(join(page, "index.html")));
 }
+function fromElsewhere(request) {
+	const { host, origin } = request.headers;
+	if (!thisMachine(host)) return `Playthrough answers only at localhost, not at “${host}”. Open http://localhost:${request.socket.localPort}/.`;
+	if (origin !== void 0 && origin !== `http://${host}`) return `Only Playthrough's own page can ask this, not ${origin}.`;
+}
+const thisMachine = (host) => /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i.test(host ?? "");
 async function body(request) {
 	const chunks = [];
 	for await (const chunk of request) chunks.push(chunk);