playthrough 0.4.0 → 0.4.2

package/INSTRUCTIONS.md

@@ -35,6 +35,9 @@ The person can only judge what the flows show, so keep them true to how a person
 
 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:
 
   { "start": "npm run dev", "url": "http://localhost:3000" }

package/README.md

@@ -1,43 +1,34 @@
-# Playthrough
+# <img src="https://raw.githubusercontent.com/itmostlyworks/playthrough/main/packages/viewer/public/logo.svg" alt="" height="28"> Playthrough
 
 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.
-
 ## Try it
 
-Playthrough needs Node 24 or later. In your app's repo:
-
-```bash
-npm install --save-dev playthrough
-npx playwright install chromium
-```
+Ask your agent for a change in your app, as you would anyway, and add:
 
-Then ask your agent for a change, and to show it to you:
+> Show me this change with `npx playthrough`.
 
-> Show only the overdue invoices. Use Playthrough to show me the change: run `npx playthrough` and follow what it says.
-
-The agent starts a review, records it, and hands it to you with `playthrough wait`. Open it:
+The agent does the rest. The first time, it adds Playthrough to your app and writes down how to start it and sign in, to commit with your app. Each time, it records the change and hands it to you. Open it:
 
 ```bash
 npx playthrough open
 ```
 
-The first time, the agent writes `playthrough/app.json`, which says how to start your app, and `playthrough/setup.ts` if flows need something first: a signed-in user, an account with data in it, or the people who use the app. Both are committed with your app, so every review after uses them.
-
-Reviews are kept in `.playthrough/` in your app's repo, recordings and all. Nothing is uploaded anywhere.
+Reviews stay in `.playthrough/` in your app's repo, recordings and all; nothing is uploaded. Playthrough needs Node 24 or later.
 
 ## 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 ask your agent for the same change from `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 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,6 +1,6 @@
 {
   "name": "playthrough",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Review an AI agent's work on a web app by watching recordings of it.",
   "type": "module",
   "license": "Apache-2.0",

package/src/playthrough.js

@@ -1717,31 +1717,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.`]);
 	}