playthrough 0.4.3 → 0.5.0

package/INSTRUCTIONS.md

@@ -38,15 +38,24 @@ THE APP
 The first time, add playthrough to the app's devDependencies with the app's own package manager, and run
 npx playwright install chromium: flows import from it, and record in that browser.
 
-playthrough/app.json says how to start the app, and is committed so every review uses it:
+playthrough/app.json says how to start the app, and is committed so every review uses it. Where the command can be
+given a port, say {port} in both, and Playthrough starts this copy of the app on a port of its own each time it records
+or the person takes a flow over, beside the person's own and any other worktree's:
+
+  { "start": "npm run dev -- --port {port}", "url": "http://localhost:{port}" }
+
+Where it can't, as when another part of the app expects it at one address, give the address it always has:
 
   { "start": "npm run dev", "url": "http://localhost:3000" }
 
+There, every round is recorded on whatever serves that url, and Playthrough starts the app only when nothing does: leave
+a server you didn't start running, and let it follow the working copy, as a dev server does. In a worktree, what serves
+it could be another copy, so Playthrough needs the address free, and says so. An app of several servers, one calling
+another at its address, takes the address it always has, or a copy on a port of its own would call the person's.
+
 Flows run several at once. Where a page shows what every run made, as a blog's index lists every post, add
-"oneAtATime": true. Every round is recorded on whatever serves that url, and Playthrough starts the app only when nothing
-does: leave a server you didn't start running, and let it follow the working copy, as a dev server does. Recording on
-Before sets your work aside with git stash for a minute, puts the app as it was in its place, with playthrough/ as it is
-now, and puts your work back after, even when Playthrough is stopped.
+"oneAtATime": true. Recording on Before sets your work aside with git stash for a minute, puts the app as it was in its
+place, with playthrough/ as it is now, and puts your work back after, even when Playthrough is stopped.
 
 FLOWS
 

package/README.md

@@ -6,6 +6,8 @@ Playthrough records your coding agent's change the way a person would use it, be
 
 To see a review before you install anything, play the one at [playthrough.sh](https://playthrough.sh).
 
+<a href="https://playthrough.sh"><img src="https://raw.githubusercontent.com/itmostlyworks/playthrough/main/docs/viewer-light.png" alt="The viewer: the agent's recording of Send a reminder, paused on your note and the agent's answer, asking whether it fixes it, with Note, Compare and Take over on the bar"></a>
+
 ## Try it
 
 Ask your agent for a change in your app, as you would anyway, and add:
@@ -20,9 +22,13 @@ npx playthrough open
 
 Reviews stay in `.playthrough/` in your app's repo, recordings and all; nothing is uploaded. Playthrough needs Node 24 or later.
 
-## On the example
+You can teach your agent Playthrough once, so “Show me this change” is enough from then on:
+
+```bash
+npx skills add itmostlyworks/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`.
+In Claude Code, it's a plugin too: `/plugin install playthrough --marketplace itmostlyworks/playthrough`.
 
 ## How a review goes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playthrough",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Review what your coding agent built in your web app by watching recordings of it.",
   "keywords": [
     "coding-agent",

package/src/{flows-BkG0TgHA.js → flows-DDB6AdQ-.js}

@@ -1,12 +1,13 @@
-import { A as list, b as Refused, g as readingsOf, j as quote, m as glimpsesOf, p as firstLine, x as Reviews } from "./reporter-DE8aueAO.js";
+import { A as quote, b as Reviews, h as readingsOf, k as list, m as glimpsesOf, p as firstLine, y as Refused } from "./reporter-Dr7dWwSf.js";
 import * as modules from "node:module";
 import { createRequire } from "node:module";
 import { existsSync, watch } from "node:fs";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import { constants, tmpdir } from "node:os";
-import { dirname, join, relative } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
+import { createServer } from "node:net";
 import { chromium, request } from "@playwright/test";
 import { fileURLToPath, pathToFileURL } from "node:url";
 // ../review/src/steps.ts
@@ -82,7 +83,7 @@ function folder(root) {
 		},
 		async write(path, bytes) {
 			const file = join(root, path);
-			const unfinished = `${file}.${process.pid}.${Date.now()}.writing`;
+			const unfinished = `${file}.${randomUUID()}.writing`;
 			await mkdir(dirname(file), { recursive: true });
 			await writeFile(unfinished, bytes);
 			await rename(unfinished, file);
@@ -132,7 +133,7 @@ function repo(root = home(process.cwd())) {
 			await writeFile(join(reviews, ".gitignore"), "*\n");
 		},
 		async app() {
-			const how = `Say how to start the app in playthrough/app.json: { "start": "<the command that serves it>", "url": "<where it's served>" }.`;
+			const how = `Say how to start the app in playthrough/app.json: ${PORTED}, or with the address it always has where it can't be given a port.`;
 			const text = await readFile(appFile, "utf8").catch(() => void 0);
 			if (text === void 0) throw new Refused([`Playthrough needs to start the app to record it. ${how}`]);
 			let app;
@@ -141,12 +142,19 @@ function repo(root = home(process.cwd())) {
 			} catch (error) {
 				throw new Refused([`playthrough/app.json isn't JSON: ${error.message}. ${how}`]);
 			}
-			if (!isText(app.start) || !isText(app.url)) throw new Refused([`playthrough/app.json needs both “start” and “url”. ${how}`]);
+			if (!app || typeof app !== "object" || !isText(app.start) || !isText(app.url)) throw new Refused([`playthrough/app.json needs both “start” and “url”. ${how}`]);
+			const saying = [app.start, app.url].filter((said) => said.includes("{port}")).length;
+			if (saying === 1) throw new Refused([`playthrough/app.json says {port} in only one of “start” and “url”. Say it in both, so the app is started on the port Playthrough gives it and found there: ${PORTED}.`]);
+			const port = saying ? await portFor(root) : void 0;
+			const given = (said) => port === void 0 ? said : said.replaceAll("{port}", String(port));
+			const url = given(app.url);
+			if (!/^https?:$/.test(URL.parse(url)?.protocol ?? "")) throw new Refused([`playthrough/app.json's “url” is a whole address, as a browser takes it, like http://localhost:{port}, not “${app.url}”.`]);
 			if (app.oneAtATime !== void 0 && typeof app.oneAtATime !== "boolean") throw new Refused([`playthrough/app.json's “oneAtATime” is true or false: true runs each flow by itself.`]);
 			return {
-				start: app.start,
-				url: app.url,
-				...app.oneAtATime && { oneAtATime: true }
+				start: given(app.start),
+				url,
+				...app.oneAtATime && { oneAtATime: true },
+				...port !== void 0 && { port }
 			};
 		}
 	};
@@ -157,6 +165,35 @@ function home(here) {
 		if (existsSync(join(folder, ".git")) || dirname(folder) === folder) return here;
 	}
 }
+const PORTED = `{ "start": "npm run dev -- --port {port}", "url": "http://localhost:{port}" }`;
+const ports = /* @__PURE__ */ new Map();
+const portFor = (root) => ports.get(root) ?? ports.set(root, free()).get(root);
+const free = () => new Promise((resolve, reject) => {
+	const server = createServer();
+	server.once("error", reject);
+	server.listen(0, "127.0.0.1", () => {
+		const { port } = server.address();
+		server.close(() => resolve(port));
+	});
+});
+function copies(root) {
+	try {
+		const git = (...args) => execFileSync("git", args, {
+			cwd: root,
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		const inside = relative(git("rev-parse", "--show-toplevel"), root);
+		return git("worktree", "list", "--porcelain").split("\n").filter((line) => line.startsWith("worktree ")).map((line) => line.slice(9)).map((worktree) => resolve(worktree, inside)).filter((folder) => existsSync(folder));
+	} catch {
+		return [resolve(root)];
+	}
+}
+const inWorktree = (root) => copies(root)[0] !== resolve(root);
 const isText = (value) => typeof value === "string" && value.trim() !== "";
 // src/setup.ts
 const OURS = [
@@ -250,8 +287,9 @@ async function giveBackOf({ after }, borrowed, whose) {
 	for (const name of left) {
 		const file = join(borrowed, `${process.pid}-${name.slice(name.indexOf("-") + 1)}`);
 		if (!await rename(join(borrowed, name), file).then(() => true, () => false)) continue;
-		const { baseURL, setup } = JSON.parse(await readFile(file, "utf8"));
-		await giveBack(after, file, baseURL, setup);
+		const given = await readFile(file, "utf8").then(JSON.parse).catch(() => void 0);
+		if (!given) await rm(file, { force: true });
+		else await giveBack(after, file, given.baseURL, given.setup);
 	}
 }
 const giving = /* @__PURE__ */ new Set();
@@ -284,7 +322,7 @@ function alive(pid) {
 	}
 }
 // src/app.ts
-let started;
+const started = /* @__PURE__ */ new Map();
 let ending = false;
 async function keepRunning(app, root) {
 	if (!ending) {
@@ -297,12 +335,17 @@ async function keepRunning(app, root) {
 			"SIGTERM",
 			"SIGHUP"
 		]) process.once(signal, end);
-		process.once("exit", stop);
+		process.once("exit", () => [...started.keys()].forEach(stop));
+	}
+	const ours = started.get(app.url);
+	if (ours && ours.root !== root) await stopApp(app.url);
+	if (await serves(app.url)) {
+		if (ours?.root === root || app.port !== void 0 || !inWorktree(root)) return;
+		throw new Refused([`Something else answers at ${app.url}, most likely the app running from another folder. This is a worktree, so Playthrough runs this copy of the app there itself: whoever started what's there can stop it, then try again.`, `Or give each copy a port of its own in playthrough/app.json: ${PORTED}.`]);
 	}
-	if (await serves(app.url)) return;
 	console.log(`Starting the app: ${app.start}`);
 	const began = Date.now();
-	started = spawn(app.start, {
+	const running = spawn(app.start, {
 		cwd: root,
 		shell: true,
 		stdio: [
@@ -312,17 +355,21 @@ async function keepRunning(app, root) {
 		],
 		detached: true
 	});
+	started.set(app.url, {
+		app: running,
+		root
+	});
 	const said = [];
-	for (const output of [started.stdout, started.stderr]) {
+	for (const output of [running.stdout, running.stderr]) {
 		output.on("data", (chunk) => {
 			said.push(...chunk.toString().split("\n").filter((line) => line.trim() && !/^\s+at /.test(line)));
 			said.splice(0, said.length - 10);
 		});
 		output.unref();
 	}
-	started.unref();
+	running.unref();
 	let ended = false;
-	started.once("exit", () => ended = true);
+	running.once("exit", () => ended = true);
 	const saying = () => said.length ? ["It said, last:", ...said.map((line) => `  ${line}`)] : [];
 	while (Date.now() - began < 18e4) {
 		if (await serves(app.url)) return Date.now() - began;
@@ -333,7 +380,7 @@ async function keepRunning(app, root) {
 		]);
 		await new Promise((resolve) => setTimeout(resolve, 250));
 	}
-	stop();
+	stop(app.url);
 	throw new Refused([
 		`The app didn't answer at ${app.url} within three minutes of ${quote(app.start)}.`,
 		...saying(),
@@ -341,16 +388,17 @@ async function keepRunning(app, root) {
 	]);
 }
 async function stopApp(url) {
-	if (!stop()) return;
+	if (!stop(url)) return;
 	const began = Date.now();
 	while (Date.now() - began < 1e4 && await serves(url)) await new Promise((resolve) => setTimeout(resolve, 250));
 }
-function stop() {
-	if (!started) return false;
+function stop(url) {
+	const ours = started.get(url);
+	if (!ours) return false;
 	try {
-		process.kill(-started.pid);
+		process.kill(-ours.app.pid);
 	} catch {}
-	started = void 0;
+	started.delete(url);
 	return true;
 }
 const serves = (url) => fetch(url, { signal: AbortSignal.timeout(2e3) }).then((response) => (response.body?.cancel(), true), (error) => error?.name === "TimeoutError");
@@ -1962,7 +2010,7 @@ async function trySetup(repo, again) {
 	const app = await repo.app();
 	const written = await writtenNow(repo);
 	const last = join(repo.tried, "tried.json");
-	if (await readFile(last, "utf8").then((text) => JSON.parse(text).written, () => void 0) === written) return;
+	if (await readFile(last, "utf8").then((text) => JSON.parse(text).written).catch(() => void 0) === written) return;
 	console.log("Trying the app's setup by itself first, twice, as every flow will start…");
 	const browser = await chromium.launch().catch((error) => {
 		const { version } = createRequire(import.meta.url)("@playwright/test/package.json");
@@ -2075,6 +2123,7 @@ async function writtenNow(repo) {
 	return createHash("sha256").update(await text(repo.appFile)).update("\0").update(await text(repo.setup)).digest("hex");
 }
 // src/flows.ts
+const recorder = join(dirname(createRequire(import.meta.url).resolve("@rrweb/record")), "record.umd.min.cjs");
 const WALKED = "walked.json";
 const ALONGSIDE = Symbol.for("playthrough: flows taken over here");
 const REACHES_OUTSIDE = "reaches outside";
@@ -2117,7 +2166,6 @@ async function runFlows(repo, id, round, { before, first = () => false }) {
 	const app = await repo.app();
 	if (!before) await trySetup(repo, `playthrough record ${id}`);
 	const { started, rounds } = await repo.reviews.get(id);
-	const recorder = join(dirname(createRequire(import.meta.url).resolve("@rrweb/record")), "record.umd.min.cjs");
 	const longest = (rounds.filter((kept) => kept.number < round).at(-1)?.flows ?? []).toSorted((a, b) => b.length - a.length).map((flow) => flow.name);
 	const run = (only, results) => runOnce({
 		flows,
@@ -2198,7 +2246,7 @@ async function keepFailed(repo, id, failed) {
 	await mkdir(folder, { recursive: true });
 	await writeFile(join(folder, FAILED), JSON.stringify(failed.map(({ flow }) => flow)));
 }
-const failedLastTime = (repo, id) => readFile(join(repo.failed(id), FAILED), "utf8").then(JSON.parse, () => []);
+const failedLastTime = (repo, id) => readFile(join(repo.failed(id), FAILED), "utf8").then(JSON.parse).catch(() => []);
 const FAILED = "flows.json";
 const whereItStopped = (repo, id, failed) => `What the page held where ${failed.length > 1 ? "each" : "it"} stopped is in ${repo.show(repo.failed(id))}/.`;
 function inMemory(number, recorded) {
@@ -2249,7 +2297,6 @@ async function runOnce(run) {
 async function walkFork(repo, id, walk) {
 	const app = await repo.app();
 	const { started } = await repo.reviews.get(id);
-	const recorder = join(dirname(createRequire(import.meta.url).resolve("@rrweb/record")), "record.umd.min.cjs");
 	const folder = await mkdtemp(join(tmpdir(), "playthrough-"));
 	try {
 		await playwright({
@@ -2318,4 +2365,4 @@ async function playwright(run) {
 		});
 	});
 }
-export { firstOf$1 as C, setupIn as D, personIn as E, repo as O, changes as S, make as T, placeIn as _, failedAt as a, serves as b, isFlow as c, waitsFor as d, walkFork as f, compareWithEarlier as g, writtenNow as h, called as i, pausedAt as k, makeFlowsFolder as l, trySetup as m, REACHES_OUTSIDE as n, flowsOf as o, whereItStopped as p, WALKED as r, howToWriteFlows as s, ALONGSIDE as t, runFlows as u, shownAt as v, giveBackLeft as w, stopApp as x, keepRunning as y };
+export { repo as A, changes as C, personIn as D, make as E, setupIn as O, stopApp as S, giveBackLeft as T, compareWithEarlier as _, failedAt as a, keepRunning as b, isFlow as c, runFlows as d, waitsFor as f, writtenNow as g, trySetup as h, called as i, pausedAt as j, copies as k, makeFlowsFolder as l, whereItStopped as m, REACHES_OUTSIDE as n, flowsOf as o, walkFork as p, WALKED as r, howToWriteFlows as s, ALONGSIDE as t, recorder as u, placeIn as v, firstOf$1 as w, serves as x, shownAt as y };