web-tester-for-claude 0.4.0

package/src/templates/dot-web-tester/instructions/recipes.md

@@ -0,0 +1,105 @@
+# Recipes
+
+Copy-paste one-liners for common web-tester runs. Add new entries as you
+discover new flows so future sessions don't re-derive the step grammar.
+
+## Format
+
+Each recipe has:
+
+- A **title** (one line, action-oriented: "Verify the contact form submits")
+- A **when** clause (one line — the trigger that should pull this recipe)
+- A **command** block — the exact shell line, ready to copy
+- An **expected outcome** line — what "pass" looks like
+
+## Template
+
+```
+### <title>
+
+**When:** <one-line trigger>
+
+**Command:**
+
+```bash
+web-tester inspect "<path>" \
+  --step settle --quick \
+  --expect "<assertion>" \
+  --fail-on http-5xx
+```
+
+**Expected:** <one line — what verdict / evidence proves the run worked>
+```
+
+---
+
+## Built-in starters
+
+### Smoke-check the homepage
+
+**When:** "is the site up?" / "did my change break the homepage?"
+
+**Command:**
+
+```bash
+web-tester inspect / \
+  --step wait:networkidle --quick \
+  --expect "selector=header" \
+  --expect "selector=footer" \
+  --expect "selector=main" \
+  --fail-on http-5xx
+```
+
+**Expected:** verdict: pass, all three selectors visible.
+
+### Verify a form submits and lands on a thank-you page
+
+**When:** "did my form change still work?"
+
+**Command:**
+
+```bash
+web-tester inspect "/contact" \
+  --step "wait:networkidle" \
+  --step "fill:input[name=email]=test@example.com" \
+  --step "fill:textarea[name=message]=hello from web-tester" \
+  --step "click:button[type=submit]" \
+  --step "wait:url-contains:/thanks@10000" \
+  --quick \
+  --expect "text=Thanks" \
+  --fail-on http-5xx
+```
+
+**Expected:** URL transitions to `/thanks`, "Thanks" text visible.
+
+### Sweep your smoke URL list against localhost
+
+**When:** structural change (layout / header / shared component) — broad regression check.
+
+**Command:**
+
+```bash
+web-tester sweep --preset smoke --fail-on http-5xx
+```
+
+**Expected:** every URL reports ok in the sweep summary; the HTML report opens to a green table.
+
+### Diff-aware advisory run
+
+**When:** about to push — "what might my diff have broken?"
+
+**Command:**
+
+```bash
+web-tester impact
+```
+
+**Expected:** plan prints matching rules, then advisory findings (or "nothing flagged"). Exits 0 either way.
+
+---
+
+## Project-specific recipes
+
+<!-- Add your project's recipes below. Copy the template above, fill it in,
+     point the URL at whatever you're testing. `web-tester map` can generate
+     a starter set of these for you. -->

package/src/templates/dot-web-tester/journeys/example-signup.json

@@ -0,0 +1,17 @@
+{
+  "description": "Example: user signs up and lands on a dashboard. Edit the URL, selectors, and expectations to match your app.",
+  "url": "/signup",
+  "steps": [
+    "wait:networkidle",
+    "fill:input[name=email]=test@example.com",
+    "fill:input[name=password]=hunter2-hunter2",
+    "click:button[type=submit]",
+    "wait:url-contains:/dashboard@15000"
+  ],
+  "expectations": [
+    "text=Welcome",
+    "selector=[data-test=dashboard]"
+  ],
+  "failOn": "http-5xx",
+  "persistMs": 0
+}

package/src/templates/dot-web-tester/urls-smoke.txt

@@ -0,0 +1,19 @@
+# urls-smoke.txt — high-value pages to sweep on any structural change.
+#
+# One path per line. `#pack=<name>` annotations apply a built-in expectation
+# pack to that URL. Built-in packs:
+#   homepage    — header + footer present
+#   static      — header + footer present
+#   category    — header + footer + at least one internal anchor with an <img> in <main>
+#   has-main    — <main> present
+#   has-h1      — <h1> present
+#
+# Run:  web-tester sweep --preset smoke --fail-on http-5xx
+#
+# These are placeholders — replace with your real routes (or generate this
+# file with `web-tester map`).
+
+/                                  #pack=homepage
+/about                             #pack=static
+/pricing                           #pack=has-h1
+/contact                           #pack=static

package/src/templates/skill.md

@@ -0,0 +1,59 @@
+---
+name: web-tester
+description: Drive the running dev site in a real browser (Playwright) to reproduce bugs, verify changes, and read runtime behavior — console, network, page errors, DOM, screenshots, video. Use this FIRST for any "does X work", bug-reproduction, "this page renders wrong", "the state is off", or "verify my change" question, before reading source. Also use to map a site, sweep many URLs, or run a saved journey.
+allowed-tools: Bash(npx web-tester-for-claude *), Bash(web-tester *), Bash(npx web-tester *), Bash(npm run web-tester *), Bash(pnpm web-tester *), Read(**)
+---
+
+# Driving the site with web-tester
+
+For any runtime-behavior question, reach for web-tester **before** Read/Grep. The
+browser is the source of truth for runtime bugs; read code *after* the run,
+guided by what the run shows.
+
+## The core loop
+
+1. **Run it** against your **localhost** dev server, always with `--quick` and
+   `--fail-on http-5xx`. Add `--expect` for the specific thing you're checking:
+
+   ```bash
+   npx web-tester-for-claude inspect "/products/widget" \
+     --step settle --quick \
+     --expect "text=Add to Cart" \
+     --fail-on http-5xx
+   ```
+
+2. **Read the report** at the path the CLI prints — `result.json` for
+   programmatic reads (`ok`, `verdictTriggers`, `expectations`, `pageErrors`,
+   `console.entries`, `network.entries`, `steps[N].evalResult`), `report.html`
+   to scrub the video. **Only then** open source files.
+
+3. **When the DOM isn't enough**, re-run with `--deep`: it adds request/response
+   bodies, the **local-scope variables at every uncaught exception**, and
+   unhandled promise rejections (`result.json` → `deepErrors`,
+   `unhandledRejections`, `network.entries[].responseBody`).
+
+## Commands
+
+| Command | Use it for |
+|---|---|
+| `inspect <url> [--step …]` | Drive one page / flow, capture everything. |
+| `sweep --preset <name>` | Health-check many URLs in parallel. |
+| `journey <name>` | Run a saved flow from `.web-tester/journeys/`. |
+| `map` | Crawl the site and auto-generate a preset, recipes, and journey drafts. |
+| `impact` | Diff-aware advisory run (reads `.web-tester/impact-rules.json`). |
+| `kb [topic]` | List/print project recipe notes in `.web-tester/instructions/`. |
+
+## Before you write a `--step` chain from scratch
+
+Run `web-tester kb` first — the project's recipes live there. Step grammar
+gotchas: `click:` takes a Playwright CSS locator (not `role=`); `settle` only
+does something on pages with `[data-attr-name]` markers — otherwise prefer
+`wait:networkidle`. Run `web-tester help` for the full grammar.
+
+## Don't
+
+- Don't verify a **local** change against **prod** — prod doesn't have your edit.
+  localhost is the default and the right target.
+- Don't `--fail-on page-errors` by default — most apps have baseline framework
+  warnings. `http-5xx` is the safe gate.
+- Don't trust a single `--expect` for async/derived state — add `--persist 2500`.

package/src/util/log.ts

@@ -0,0 +1,26 @@
+/* eslint-disable no-console */
+
+const COLORS = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m"
+};
+
+export const log = {
+  info: (msg: string): void => console.log(msg),
+  dim: (msg: string): void =>
+    console.log(`${COLORS.dim}${msg}${COLORS.reset}`),
+  ok: (msg: string): void =>
+    console.log(`${COLORS.green}${msg}${COLORS.reset}`),
+  warn: (msg: string): void =>
+    console.log(`${COLORS.yellow}${msg}${COLORS.reset}`),
+  fail: (msg: string): void => console.log(`${COLORS.red}${msg}${COLORS.reset}`),
+  step: (msg: string): void => console.log(`${COLORS.cyan}${msg}${COLORS.reset}`),
+  header: (msg: string): void =>
+    console.log(`${COLORS.blue}\n=== ${msg} ===${COLORS.reset}`),
+  raw: (msg: string): void => console.log(msg)
+};

package/src/util/paths.ts

@@ -0,0 +1,141 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+/** Root of the installed package (used to resolve bundled templates). */
+export const PACKAGE_ROOT = resolve(__dirname, "../..");
+
+/** Bundled scaffolding consumed by `web-tester init`. */
+export const TEMPLATES_DIR = resolve(PACKAGE_ROOT, "src/templates");
+
+/**
+ * Where run artifacts are written. Defaults to `.web-tester/runs/` in the
+ * project the CLI was invoked from, so output is namespaced under one dir
+ * (which `init` adds to `.gitignore`) rather than dropping a stray top-level
+ * `runs/`. Override with `WEB_TESTER_RUNS_DIR`.
+ */
+export const RUNS_DIR = process.env.WEB_TESTER_RUNS_DIR
+  ? resolve(process.env.WEB_TESTER_RUNS_DIR)
+  : resolve(process.cwd(), ".web-tester", "runs");
+
+/**
+ * Project config lives in `.web-tester/` at the project root, resolved
+ * against `process.cwd()`. Everything in it is optional:
+ *
+ *   .web-tester/
+ *     impact-rules.json        rules for `web-tester impact`
+ *     urls-<name>.txt          URL presets for `web-tester sweep --preset <name>`
+ *     journeys/<name>.json     named flows for `web-tester journey <name>`
+ *     instructions/*.md        knowledge base for `web-tester kb [topic]`
+ */
+export const USER_CONFIG_DIRNAME = ".web-tester";
+
+export function userConfigDir(cwd: string = process.cwd()): string {
+  return resolve(cwd, USER_CONFIG_DIRNAME);
+}
+
+export function userImpactRulesPath(cwd: string = process.cwd()): string {
+  return resolve(userConfigDir(cwd), "impact-rules.json");
+}
+
+export function userJourneysDir(cwd: string = process.cwd()): string {
+  return resolve(userConfigDir(cwd), "journeys");
+}
+
+export function userPresetsDir(cwd: string = process.cwd()): string {
+  // Presets are flat `urls-<name>.txt` files at the top of `.web-tester/`.
+  return userConfigDir(cwd);
+}
+
+/**
+ * KB markdown locations, in priority order: `.web-tester/instructions/`
+ * first, then `.web-tester/` itself. First existing dir wins.
+ */
+export function userKnowledgeDirs(cwd: string = process.cwd()): string[] {
+  return [resolve(userConfigDir(cwd), "instructions"), userConfigDir(cwd)];
+}
+
+/** `.web-tester/config.json` — persistent project defaults written by `init`. */
+export function projectConfigPath(cwd: string = process.cwd()): string {
+  return resolve(userConfigDir(cwd), "config.json");
+}
+
+export type ProjectConfig = {
+  /** Default base URL, used when `WEB_TESTER_BASE_URL` isn't set. */
+  baseUrl?: string;
+};
+
+/** Read `.web-tester/config.json`. Returns {} when missing or unreadable. */
+export function readProjectConfig(cwd: string = process.cwd()): ProjectConfig {
+  try {
+    const path = projectConfigPath(cwd);
+    if (!existsSync(path)) return {};
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as ProjectConfig;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The project's `.claude/` integration directory and the files `init` touches. */
+export function claudeDir(cwd: string = process.cwd()): string {
+  return resolve(cwd, ".claude");
+}
+
+export function claudeSettingsLocalPath(cwd: string = process.cwd()): string {
+  return resolve(claudeDir(cwd), "settings.local.json");
+}
+
+/** `.claude/skills/web-tester/SKILL.md` — the generated Claude Code skill. */
+export function claudeSkillPath(cwd: string = process.cwd()): string {
+  return resolve(claudeDir(cwd), "skills", "web-tester", "SKILL.md");
+}
+
+/**
+ * Machine-local state in `~/.web-tester/`, kept outside the repo so saved
+ * auth state is never committed. Holds the Playwright `storageState` dump
+ * (cookies + localStorage) when a run persists a session.
+ */
+export const WEB_TESTER_HOME = resolve(homedir(), ".web-tester");
+export const SESSION_STATE_PATH = resolve(WEB_TESTER_HOME, "session.json");
+
+export function ensureWebTesterHome(): void {
+  mkdirSync(WEB_TESTER_HOME, { recursive: true });
+}
+
+export function newRunId(): string {
+  const now = new Date();
+  const pad = (n: number): string => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(
+    now.getDate()
+  )}T${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+}
+
+export type RunPaths = {
+  runId: string;
+  runDir: string;
+  stepsDir: string;
+  videoDir: string;
+  resultPath: string;
+  reportHtmlPath: string;
+  consolePath: string;
+  networkPath: string;
+};
+
+export function ensureRunPaths(runId: string): RunPaths {
+  const runDir = resolve(RUNS_DIR, runId);
+  const stepsDir = resolve(runDir, "steps");
+  const videoDir = resolve(runDir, "video");
+  mkdirSync(stepsDir, { recursive: true });
+  mkdirSync(videoDir, { recursive: true });
+  return {
+    runId,
+    runDir,
+    stepsDir,
+    videoDir,
+    resultPath: resolve(runDir, "result.json"),
+    reportHtmlPath: resolve(runDir, "report.html"),
+    consolePath: resolve(runDir, "console.json"),
+    networkPath: resolve(runDir, "network.json")
+  };
+}

package/src/util/prompt.ts

@@ -0,0 +1,50 @@
+import { createInterface } from "node:readline";
+
+/** True when we can run an interactive prompt (both ends are a TTY). */
+export function isInteractive(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function question(query: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise<string>((resolve) => {
+    rl.question(query, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/** Free-text prompt with a default shown in brackets. Empty input → default. */
+export async function ask(label: string, def: string): Promise<string> {
+  const answer = (await question(`${label} [${def}]: `)).trim();
+  return answer || def;
+}
+
+/** Yes/no prompt. Empty input → default. */
+export async function confirm(label: string, def: boolean): Promise<boolean> {
+  const hint = def ? "Y/n" : "y/N";
+  const answer = (await question(`${label} (${hint}): `)).trim().toLowerCase();
+  if (!answer) return def;
+  return answer === "y" || answer === "yes";
+}
+
+/**
+ * Pick one of `options`. Accepts a full value or a unique prefix
+ * (case-insensitive). Empty input → default.
+ */
+export async function choice<T extends string>(
+  label: string,
+  options: readonly T[],
+  def: T
+): Promise<T> {
+  const rendered = options
+    .map((o) => (o === def ? o.toUpperCase() : o))
+    .join("/");
+  const answer = (await question(`${label} [${rendered}]: `)).trim().toLowerCase();
+  if (!answer) return def;
+  const match = options.find(
+    (o) => o.toLowerCase() === answer || o.toLowerCase().startsWith(answer)
+  );
+  return match ?? def;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"]
+}