@tamsensedev/runner 0.1.0 → 0.3.0

package/library/skills/ui-testing/references/headless-check.md

@@ -2,7 +2,7 @@
 
 Read this when the project has no Playwright or Cypress tests you can run for the change, but you still need to see the pages: screenshots, console errors, failed requests, horizontal overflow on narrow screens, and optionally an axe scan.
 
-The script below starts the app with the project's own command on a free port, waits for it, opens each page headless at a desktop and a phone width, runs optional steps you write, saves screenshots and a JSON summary to a temp folder, and stops the app and all its child processes at the end.
+The script below starts the app with the project's own command on a free port, waits for it, opens each page headless at a desktop and a phone width, runs optional steps you write, saves screenshots and a JSON summary to a temp folder, and stops the app and all its child processes at the end. In a TAMsense run each page and width is also recorded as a replay for the task, named from `CONFIG.title` and `CONFIG.purpose` (see [recording.md](recording.md)).
 
 ## What it needs
 
@@ -14,7 +14,7 @@ The script below starts the app with the project's own command on a free port, w
 ## How to use it
 
 1. Make a new folder in the OS temp directory (`node -p "require('os').tmpdir()"`), for example `<tmp>/ui-check-<random>`. Never inside the repository.
-2. Write the script there as `ui-check.mjs` and edit only the `CONFIG` block and the `steps` function.
+2. Write the script there as `ui-check.mjs` and edit only the `CONFIG` block and the `steps` function. Set `title` and `purpose` to what this check is and why ("Feature testing, attempt 2", "Checking the empty orders state after the fix"), and `video: true` when the pages have a canvas, a map, a video player or iframes from another site.
 3. Run `node <tmp>/ui-check-<random>/ui-check.mjs` with a timeout of a few minutes. It prints the summary; screenshots are in `CONFIG.outDir`.
 4. Open the screenshots with the Read tool and look at them. Describe in the report what each one shows; the paths alone mean nothing to the reader.
 5. Delete the folder when the report is written, unless the task asks you to keep artifacts.
@@ -41,13 +41,18 @@ const CONFIG = {
     widths: [1280, 390],
     startTimeoutMs: 120_000,
     navigationTimeoutMs: 30_000,
+    title: 'Feature testing',
+    purpose: 'Checking the changed screens at desktop and phone width',
+    video: false,
 }
 
-async function steps(page, { path, width }) {
+async function steps(page, { path, width, mark }) {
 }
 
 const MAX_ITEMS = 20
+const MAX_TITLE = 60
 const serverOutput = []
+const recorder = process.env.TAMSENSE_RECORDER ? createRequire(import.meta.url)(process.env.TAMSENSE_RECORDER) : null
 
 function keepTail(chunk) {
     serverOutput.push(...String(chunk).split('\n').filter(Boolean))
@@ -162,9 +167,18 @@ async function runAxe(page, axeSource) {
     }
 }
 
+async function openContext(browser, path, width) {
+    const options = { viewport: { width, height: 900 } }
+    if (!recorder) return browser.newContext(options)
+    const where = `, ${path} at ${width}px`
+    const title = `${CONFIG.title.slice(0, MAX_TITLE - where.length)}${where}`
+    return recorder.newRecordedContext(browser, { title, purpose: CONFIG.purpose, video: CONFIG.video, context: options })
+}
+
 async function checkPage(browser, url, path, width, axeSource) {
-    const context = await browser.newContext({ viewport: { width, height: 900 } })
+    const context = await openContext(browser, path, width)
     const page = await context.newPage()
+    const mark = label => recorder?.mark(page, label)
     const result = { path, width, consoleErrors: [], pageErrors: [], failedRequests: [], badResponses: [] }
     const add = (list, item) => { if (list.length < MAX_ITEMS) list.push(item) }
     page.on('console', message => { if (message.type() === 'error') add(result.consoleErrors, message.text()) })
@@ -175,7 +189,8 @@ async function checkPage(browser, url, path, width, axeSource) {
         const response = await page.goto(url, { waitUntil: 'load', timeout: CONFIG.navigationTimeoutMs })
         result.status = response?.status() ?? null
         await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => {})
-        result.steps = await steps(page, { path, width })
+        await mark(`Opened ${path}`)
+        result.steps = await steps(page, { path, width, mark })
         result.title = await page.title()
         result.finalUrl = page.url()
         result.horizontalOverflowPx = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth)
@@ -186,7 +201,7 @@ async function checkPage(browser, url, path, width, axeSource) {
     } catch (error) {
         result.error = String(error.message).split('\n')[0]
     } finally {
-        await context.close()
+        result.recording = recorder ? await recorder.closeRecorded(context) : await context.close()
     }
     return result
 }
@@ -236,15 +251,17 @@ main().catch(error => {
 
 ## Writing steps
 
-`steps` runs on every page and width before the screenshot. Use it to reach the state the task changed: open the dialog, fill and submit the form, switch the tab. Branch on `path` when pages need different steps. Whatever it returns is saved as `steps` in that page's summary (for example the focus order from a keyboard pass, see the `accessibility` skill). Use the same rules as in tests: role and label locators, web-first waits, no fixed sleeps (see [playwright-patterns.md](playwright-patterns.md)).
+`steps` runs on every page and width before the screenshot. Use it to reach the state the task changed: open the dialog, fill and submit the form, switch the tab. Branch on `path` when pages need different steps. Call `await mark('...')` after each meaningful step: the marks show on the replay's timeline for the people on the task. Whatever it returns is saved as `steps` in that page's summary (for example the focus order from a keyboard pass, see the `accessibility` skill). Use the same rules as in tests: role and label locators, web-first waits, no fixed sleeps (see [playwright-patterns.md](playwright-patterns.md)).
 
 ```js
-async function steps(page, { path }) {
+async function steps(page, { path, mark }) {
     if (path !== '/settings') return
     await page.getByRole('button', { name: 'Edit profile' }).click()
+    await mark('Opened the profile form')
     await page.getByLabel('Display name').fill('A very long display name that should wrap or truncate')
     await page.getByRole('button', { name: 'Save' }).click()
     await page.getByRole('status').waitFor()
+    await mark('Saved a long display name')
 }
 ```
 
@@ -253,6 +270,7 @@ Steps that write data only touch the local app and whatever local database it us
 ## Reading the summary
 
 - `server`: should be `stopped`. Anything else names a process you must stop yourself before finishing.
+- `recording`: where each page's replay (and video) is. They are attached to the task when the run ends; `attach_replay` and `attach_video` attach one sooner.
 - `setupError`: the app or the browser did not start. Report it with the last lines of `serverOutputTail` (strip anything that looks like a secret). Do not retry with a different command unless the first one was clearly wrong, and never invent results.
 - `status` 4xx or 5xx, `pageErrors`, `consoleErrors`: real findings when they come from the changed code; noise from browser extensions does not exist here, but third-party scripts and dev-server warnings do. Say which is which.
 - `badResponses` and `failedRequests`: API calls the page needed that failed. A 401 or a redirect to a login page means the page needs a signed-in user (see the auth section of [playwright-patterns.md](playwright-patterns.md)).

package/library/skills/ui-testing/references/local-stand.md

@@ -0,0 +1,51 @@
+# Starting a local copy of the app
+
+Read this before you start the app for a check. In a TAMsense run the task folder is a fresh checkout: no dependencies, no `.env`, nothing running. You set up a local copy from this checkout yourself, every time, and you take it down at the end. The person's own setup, their databases and every shared server stay untouched.
+
+## The rules
+
+1. **This task folder only.** Everything you start comes from the checkout in the task folder. Never read or copy `.env` files, keys or settings from elsewhere on this computer, including the person's own checkout of the same project.
+2. **Find the local setup yourself.** Look in the README, compose files named local or dev (`docker-compose.local.yml`, `infra/compose/local.compose.yml`, `compose.dev.yaml`), `.env.example` and other env files meant for a local run (`.env.local.example`, `.env.development`), and the package scripts (`dev`, `db:migrate`, `db:seed`). The CI workflow often shows the exact services and commands.
+3. **Check every address before you start.** In the settings you use, databases, caches, queues and APIs must point at `localhost`, `127.0.0.1` or containers you start. A staging, shared dev or production address, or a cloud host you do not start, means stop (rule 7). Keys of outside services (payments, mail, analytics, storage, AI APIs) stay empty; never fill them with real ones. Check variables by name and address only; never print secrets.
+4. **Your own compose project on free ports.** Start containers as a separate compose project named `tamsense-task-<task id>`, so they never mix with the person's containers. Map them to free host ports with an override file in a temp folder, not by editing the project's files. Find a free port by asking the system (`node -e "const s=require('net').createServer().listen(0,()=>{console.log(s.address().port);s.close()})"`).
+5. **Never touch containers you did not start.** Do not stop, restart, remove or change other containers, volumes or networks, even when a port is taken: pick another port.
+6. **Clean up.** At the end run `docker compose -p tamsense-task-<task id> down -v` with the same files, stop the app by its process id, and delete the temp folder.
+7. **When it cannot run, stop.** If Docker is not running, the project has no local setup, or the settings point outside this computer, do not start anything and do not look for a workaround. In a check step, call `submit_verdict` with `passed: false` and `couldNotRun: true`, write the exact reason and what a person should do in the report ("Docker is not running: start Docker Desktop and run this step again"), and do not hand off. The task then waits on this step for a person. In a code step, say so in your report.
+
+The browser adds a guard of its own: requests other than GET, HEAD and OPTIONS to an address outside this computer are aborted (see [recording.md](recording.md)). It does not replace rule 3: the app's server talks to its database and services directly.
+
+## Example
+
+Task 40, a project with `infra/compose/local.compose.yml` (postgres and redis), `.env.example` pointing at `localhost:5432` and `localhost:6379`, and a `dev` script.
+
+```bash
+docker info --format '{{.ServerVersion}}'   # an error here means Docker is not running: stop (rule 7)
+TMP=$(node -p "require('fs').mkdtempSync(require('path').join(require('os').tmpdir(), 'tamsense-task-40-'))")
+
+# free host ports for the two services, found as in rule 4
+cat > "$TMP/ports.override.yml" <<'EOF'
+services:
+  postgres:
+    ports: !override
+      - "55432:5432"
+  redis:
+    ports: !override
+      - "56379:6379"
+EOF
+
+docker compose -p tamsense-task-40 -f infra/compose/local.compose.yml -f "$TMP/ports.override.yml" up -d postgres redis
+
+pnpm install --frozen-lockfile
+# settings from .env.example, with the ports changed to the free ones, passed as variables, not written into the repository
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/app REDIS_URL=redis://localhost:56379
+pnpm db:migrate                              # migrations go to the local database only
+BROWSER=none pnpm dev --port 53100           # the project's own dev script on a free port; note its process id
+
+# ... the headless check against http://localhost:53100 ...
+
+# stop the dev server by its process id, then
+docker compose -p tamsense-task-40 -f infra/compose/local.compose.yml -f "$TMP/ports.override.yml" down -v
+rm -rf "$TMP"
+```
+
+Before `db:migrate`, look at the address once more: `DATABASE_URL` must name `localhost` and the port of your container. `!override` (Docker Compose 2.24 or newer) replaces the project's own port list instead of adding to it, so nothing binds the ports the person's own containers may use.

package/library/skills/ui-testing/references/playwright-patterns.md

@@ -1,6 +1,6 @@
 # Playwright patterns: locators, waiting, flakes, auth, mocking
 
-Read this when you write, fix or review browser tests or the `steps` of a headless check. Examples are Playwright Test in TypeScript; translate to the project's language and runner. If the project uses Cypress, the same ideas apply (see the last section). Check the installed version (`npx playwright --version`) before using an API you are not sure exists in it.
+Read this when you write, fix or review browser tests or the `steps` of a headless check. In a TAMsense run every browser context, also those of the project's tests, is recorded for the task; scripts of your own name their recordings as [recording.md](recording.md) shows. Examples are Playwright Test in TypeScript; translate to the project's language and runner. If the project uses Cypress, the same ideas apply (see the last section). Check the installed version (`npx playwright --version`) before using an API you are not sure exists in it.
 
 ## Locators
 

package/library/skills/ui-testing/references/recording.md

@@ -0,0 +1,58 @@
+# Recording the browser for the task
+
+Read this before any script that opens a browser during a TAMsense run. People on the task watch what your browser did: every page is recorded as a replay (the DOM, clicks and typing, played back in the TAMsense player) and attached to the task when the run ends.
+
+## What happens by itself
+
+- When the `TAMSENSE_RECORDER` environment variable is set, every Node process you start loads the TAMsense recorder, and every Playwright browser context is recorded, also the ones opened by the project's own E2E tests. You cannot switch this off, and you do not need to.
+- Requests from the tested site to the TAMsense tracker (`/api/events` with a `?key=` or sent to the TAMsense server) are answered by the recorder and never leave the browser, so your runs do not reach the product's analytics.
+- Requests other than GET, HEAD and OPTIONS to an address outside this computer (anything but `localhost`, `*.localhost` and loopback addresses) are aborted, so a test run never writes to an outside service. The summary from `closeRecorded` counts them in `blockedExternalWrites`. If a flow you check needs such a write, it was set up against an outside service: say so instead of working around it.
+- Password fields are masked in the replay.
+- Recordings you did not attach yourself are attached when the run ends. Unnamed ones get the step name as their title, so name yours.
+
+## What you add in every browser script
+
+Load the recorder and open each context through it, with a title and a purpose:
+
+```js
+import { createRequire } from 'node:module'
+
+const recorder = process.env.TAMSENSE_RECORDER ? createRequire(import.meta.url)(process.env.TAMSENSE_RECORDER) : null
+
+const context = recorder
+    ? await recorder.newRecordedContext(browser, {
+        title: 'Checkout testing, attempt 2',
+        purpose: 'Paying with a saved card after the fix to the total',
+        context: { viewport: { width: 1280, height: 900 } },
+    })
+    : await browser.newContext({ viewport: { width: 1280, height: 900 } })
+const page = await context.newPage()
+
+await page.goto(url)
+await recorder?.mark(page, 'Opened checkout')
+await page.getByRole('button', { name: 'Pay' }).click()
+await recorder?.mark(page, 'Paid, the receipt is shown')
+
+const recorded = recorder ? await recorder.closeRecorded(context) : await context.close()
+console.log(JSON.stringify(recorded, null, 2))
+```
+
+- `title`: what it shows, at most 60 characters. Number design variants ("Design option 1", "Design option 2") and name test runs by their goal and attempt ("Feature testing", "Second attempt at feature testing"). Never generic names like "screenshot1" or "test".
+- `purpose`: one line, at most 160 characters, on why it was made ("Comparing two layouts for the empty orders state").
+- `mark(page, label)`: call it at each meaningful step (opened a screen, submitted a form, saw the error). Marks show on the replay's timeline, and a click on one jumps there.
+- `closeRecorded(context)`: closes the context, finishes the files and returns where they are. Close every context this way, or at least with `context.close()`, before the script ends.
+- Without `TAMSENSE_RECORDER` (not a TAMsense run) the script works as before.
+
+## When to add a video
+
+A replay rebuilds the page from its DOM, so it cannot show pixels drawn by the page itself. Pass `video: true` to `newRecordedContext` as well when the screen has:
+
+- a `<canvas>` (charts drawn on canvas, editors, games), a map, or a `<video>` player;
+- iframes from another site (payment forms, embedded widgets);
+- or when someone in the chat asks for a video.
+
+`closeRecorded` warns when it saw a canvas, a video or a cross-origin iframe on a page recorded without video. Videos are larger (up to 200 MB each, 5 per run), so keep them short.
+
+## Attaching earlier
+
+Everything is attached at the end of the run. To attach a recording sooner, or with a better title, call `attach_replay` (the `.rrweb.ndjson` file) or `attach_video` (the `.webm` file) with the path from `closeRecorded`, a title and a purpose. A run attaches at most 20 replays and 5 videos; the ones you named come first.

package/package.json

@@ -1,45 +1,46 @@
-{
-    "name": "@tamsensedev/runner",
-    "type": "module",
-    "version": "0.1.0",
-    "description": "Connects your computer to TAMsense so it can work on your tasks",
-    "author": "TAMsense",
-    "license": "UNLICENSED",
-    "homepage": "https://my.tamsense.com",
-    "keywords": [
-        "tamsense",
-        "claude-code",
-        "agents",
-        "tasks"
-    ],
-    "publishConfig": {
-        "access": "public"
-    },
-    "bin": {
-        "tamsense-runner": "./dist/cli.js"
-    },
-    "files": [
-        "dist",
-        "library"
-    ],
-    "engines": {
-        "node": ">=22"
-    },
-    "scripts": {
-        "build": "tsup",
-        "dev": "tsup --watch",
-        "clean": "rimraf dist",
-        "prepublishOnly": "tsup",
-        "test": "node --experimental-strip-types --no-warnings --import ./test/resolve.mjs --test \"test/*.test.ts\""
-    },
-    "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.3.300",
-        "zod": "^4.0.0"
-    },
-    "devDependencies": {
-        "@types/node": "^22.0.0",
-        "rimraf": "^6.0.1",
-        "tsup": "^8.5.0",
-        "typescript": "^5.5.4"
-    }
-}
+{
+    "name": "@tamsensedev/runner",
+    "type": "module",
+    "version": "0.3.0",
+    "description": "Connects your computer to TAMsense so it can work on your tasks",
+    "author": "TAMsense",
+    "license": "UNLICENSED",
+    "homepage": "https://my.tamsense.com",
+    "keywords": [
+        "tamsense",
+        "claude-code",
+        "agents",
+        "tasks"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "tamsense-runner": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "library"
+    ],
+    "engines": {
+        "node": ">=22"
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "clean": "rimraf dist",
+        "prepublishOnly": "tsup",
+        "test": "node --experimental-strip-types --no-warnings --import ./test/resolve.mjs --test \"test/*.test.ts\""
+    },
+    "dependencies": {
+        "@anthropic-ai/claude-agent-sdk": "^0.3.300",
+        "rrweb": "2.0.0-alpha.20",
+        "zod": "^4.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "rimraf": "^6.0.1",
+        "tsup": "^8.5.0",
+        "typescript": "^5.5.4"
+    }
+}