playthrough 0.4.1 → 0.4.3

package/README.md

@@ -4,13 +4,7 @@ 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.
 
-## How a review goes
-
-1. You ask your agent for a change, and to show it to you with Playthrough.
-2. Before it touches the code, the agent writes a flow for each thing a person does that the change touches, and Playthrough keeps the app as it is: Before.
-3. The agent makes the change, and Playthrough records every flow, on the app as it is now and on Before, as far as the app went before. It finds what changed itself, including what the agent didn't mention, and the agent says why each change is there.
-4. You watch. Leave a note on what's wrong, where it's wrong; compare with Before; take over and try it yourself. Then send.
-5. The agent answers each note in the next round, on the spot the note is on. You check its answers, and accept once every flow looks good.
+To see a review before you install anything, play the one at [playthrough.sh](https://playthrough.sh).
 
 ## Try it
 
@@ -28,7 +22,15 @@ Reviews stay in `.playthrough/` in your app's repo, recordings and all; nothing
 
 ## On the example
 
-`example/` in this repo is a small invoices app to try it on before your own. Clone the repo, run `npm install`, `npx playwright install chromium` and `npm run build`, and from `example/`, ask your agent to show only the overdue invoices, and to show you the change with `npx playthrough`.
+`example/` in this repo is a small invoices app to try it on before your own. Clone the repo, run `npm install`, `npx playwright install chromium` and `npm run build`, and from `example/`, ask your agent to show how much is overdue in total under the Invoices heading, and to show you the change with `npx playthrough`.
+
+## How a review goes
+
+1. You ask your agent for a change, and to show it to you with Playthrough.
+2. Before it touches the code, the agent writes a flow for each thing a person does that the change touches, and Playthrough keeps the app as it is: Before.
+3. The agent makes the change, and Playthrough records every flow, on the app as it is now and on Before, as far as the app went before. It finds what changed itself, including what the agent didn't mention, and the agent says why each change is there.
+4. You watch. Leave a note on what's wrong, where it's wrong; compare with Before; take over and try it yourself. Then send.
+5. The agent answers each note in the next round, on the spot the note is on. You check its answers, and accept once every flow looks good.
 
 ## In the viewer
 

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "playthrough",
-  "version": "0.4.1",
-  "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);
@@ -1717,31 +1744,38 @@ function done({ does, with: given, what }) {
 const share = (fraction) => `${Math.round(fraction * 100)}%`;
 // src/playthrough.ts
 const HELP = readFileSync(new URL("../INSTRUCTIONS.md", import.meta.url), "utf8").trimEnd();
-const [command, review, ...words] = process.argv.slice(2);
+const given = process.argv.slice(2);
+const [command, review, ...words] = given;
 const needs = (usage) => new Refused([`That needs more: ${usage}`]);
+const takes = {
+	start: [2, `playthrough start <review> "<title>" "<what was asked>"`],
+	record: [0, "playthrough record <review>"],
+	wait: [0, "playthrough wait <review>"],
+	walk: [0, "playthrough walk <review>"],
+	open: [0, "playthrough open [<review>]"],
+	"take-over": [2, `playthrough take-over <review> "<flow>" ["<step>"]`]
+};
+const limit = Object.hasOwn(takes, command ?? "") ? takes[command] : void 0;
 try {
-	if (!command || [
-		"help",
-		"--help",
-		"-h"
-	].includes(command)) console.log(HELP);
+	if (!command || command === "help" || given.some((word) => ["--help", "-h"].includes(word))) console.log(HELP);
+	else if (limit && words.length > limit[0]) throw new Refused([`That's more than it takes: ${limit[1]}`]);
 	else {
 		await putBack(repo());
 		if (command === "start") {
-			if (!review) throw needs(`playthrough start <review> "<title>" "<what was asked>"`);
+			if (!review) throw needs(takes.start[1]);
 			await start(repo(), review, words[0], words[1]);
 		} else if (command === "record") {
-			if (!review) throw needs("playthrough record <review>");
+			if (!review) throw needs(takes.record[1]);
 			await record(repo(), review);
 		} else if (command === "wait") {
-			if (!review) throw needs("playthrough wait <review>");
+			if (!review) throw needs(takes.wait[1]);
 			await wait(repo(), review);
 		} else if (command === "walk") {
-			if (!review) throw needs("playthrough walk <review>");
+			if (!review) throw needs(takes.walk[1]);
 			await walk(repo(), review);
 		} else if (command === "open") await open(repo(), review);
 		else if (command === "take-over") {
-			if (!review) throw needs(`playthrough take-over <review> "<flow>" ["<step>"]`);
+			if (!review) throw needs(takes["take-over"][1]);
 			await takeOver$1(repo(), review, words[0], words[1]);
 		} else throw new Refused([`There's no command “${command}”. Run playthrough alone for what each one does.`]);
 	}