@sous-io/sous 0.1.0

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/SKILL.tpl.md

@@ -0,0 +1,102 @@
+---
+name: about-automated-browser-tasks
+description: >
+  YOU MUST load this skill when the user asks you to do anything that requires
+  interacting with a web browser, or when no MCP server or API can accomplish a
+  task and the only path forward is browser-based actions. Before telling the
+  user to do something manually in a browser, check for an existing automation
+  script and offer to run or write one. When browser work is needed, look for an
+  existing script first; create one only if none exists.
+user-invocable: false
+---
+
+# Automated Browser Tasks
+
+This system lets you write, run, and reuse headless browser automation scripts
+(Playwright) that authenticate as the user by borrowing their existing Chrome
+session — no manual login, no visible browser, Chrome stays open.
+
+When a task needs a browser and no API/MCP server can do it, this is the default
+path. Do not instruct the user to click through a browser manually if the task
+can be scripted.
+
+## How It Works (cold-start orientation)
+
+1. **Auth is automatic.** A harness reads cookies from the user's Chrome profile,
+   decrypts them locally (via the OS keyring), and injects them into a fresh
+   headless browser context. Scripts "just work" as the logged-in user.
+2. **Scripts are small modules.** Each script file exports `meta` (name,
+   description, params) and `execute(ctx)`. The harness resolves + validates
+   params, builds `ctx`, and runs `execute`.
+3. **You run scripts by absolute path** through the runner:
+   ```bash
+   node <scriptsDir>/run.mjs <absolute-path-to-script.mjs> [--param=value ...]
+   ```
+4. **Scripts return a result object**; the runner prints it and writes any
+   `outputFile`. Auth failures are detected and reported with an actionable
+   message telling the user to log in, then you retry.
+
+The framework code (harness, chrome-state, keyring, logger, utils, params,
+run) lives in this skill's `scripts/` directory. User scripts live in the
+project's configured scripts directory and are invoked by path.
+
+## The `ctx` Object
+
+Every script's `execute(ctx)` receives:
+
+- `ctx.page` — Playwright `Page`
+- `ctx.context` / `ctx.browser` — Playwright context / browser
+- `ctx.params` — fully resolved + validated params
+- `ctx.settings` — compiled project settings (from `settings.mjs`)
+- `ctx.timeout` — overall timeout (ms)
+- `ctx.logger` — prefixed logger; `ctx.logger.child('section')` for sections
+- `ctx.utils` — generic action helpers (modal dismissal, waits, text extraction, …)
+- `ctx.debug` — exploration & debugging tools (dump, describe, findText, watch, …)
+- `ctx.checkAuth()` — throws `AuthError` if redirected to a login page
+- `ctx.runChild(script, params)` — run another script in the same browser context
+
+Full details: [references/ctx-api.md](references/ctx-api.md).
+
+## Writing Scripts — Non-Negotiable Conventions
+
+- `execute()` is a thin orchestrator; logic lives in small named step functions.
+- EVERY function (including `execute`) has a full JSDoc block (`@param`/`@returns`).
+- Destructure what you need off `ctx`/`params` at the top of each function.
+- Use `ctx.logger`, never `console.log`.
+- Do NOT validate params in the script — declare rules in `meta.params`.
+- Fail fast; do not catch-and-continue. Fix root causes, not symptoms.
+
+Full conventions: [references/script-conventions.md](references/script-conventions.md).
+
+## Reference Files
+
+- [references/architecture.md](references/architecture.md) — components and data flow
+- [references/ctx-api.md](references/ctx-api.md) — complete `ctx` and `ctx.utils` API
+- [references/auth-and-sessions.md](references/auth-and-sessions.md) — how auth works, auth failures, retries
+- [references/script-conventions.md](references/script-conventions.md) — full scriptwriting rules
+- [references/installation.md](references/installation.md) — dependencies and setup
+
+## Examples
+
+- [examples/simple-fetch.mjs](examples/simple-fetch.mjs) — single-page data extraction
+- [examples/chained-workflow.mjs](examples/chained-workflow.mjs) — a script calling another via `ctx.runChild`
+- [examples/auth-failure-handling.mjs](examples/auth-failure-handling.mjs) — the auth-failure + retry pattern
+
+# Other Skills
+
+The agent performing the work MUST load `create-automated-browser-task` when
+creating a new automation script, `update-automated-browser-task` when modifying an
+existing script, and `running-automated-browser-tasks` when running a script.
+
+Per the sub-agent delegation pattern
+(`~sous-shared/_partials/sub-agent-delegation.md`), all three are delegated to a background
+sub-agent, which loads the skills itself and reports back. Auth failures and other
+user-facing messages go to the orchestrator to relay; sub-agents cannot talk to the
+user.
+
+## Source for this Skill
+
+This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
+the output file should not be edited directly.
+
+- Source Path: {{ sousTemplatePath }}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/examples/auth-failure-handling.mjs

@@ -0,0 +1,81 @@
+/**
+ * auth-failure-handling
+ *
+ * Demonstrates the auth-failure contract. Scripts do NOT log in and do NOT
+ * recover mid-run: they call `ctx.checkAuth()` after navigation and let the
+ * harness convert a login-page redirect into a structured auth error. The agent
+ * relays the message, the user logs in, and the SAME command is re-run.
+ *
+ * This script targets a page that requires authentication and simply reports
+ * whether it reached real content — illustrating where checkAuth belongs.
+ */
+
+export const meta = {
+  name: 'auth-failure-handling',
+  description: 'Visit an authenticated page and confirm we are logged in (auth-pattern demo).',
+  params: {
+    url: {
+      required: true,
+      description:
+        'Absolute URL of a page that requires authentication. If the Chrome ' +
+        'session is expired, the harness will surface an actionable auth error.',
+      validate: /^https?:\/\/.+/,
+      invalidMessage: 'url must be an absolute http(s) URL.',
+    },
+    readySelector: {
+      required: true,
+      description:
+        'CSS selector for an element that only appears once the authenticated ' +
+        'content has loaded (e.g. a user avatar or app shell). Used to confirm we ' +
+        'are past any login wall.',
+    },
+  },
+};
+
+/**
+ * Entry point. Navigates, checks auth, then confirms authed content rendered.
+ *
+ * @param {object} ctx - The harness context.
+ * @returns {Promise<object>} `{ found, url, message }`.
+ */
+export async function execute(ctx) {
+  const { page, params } = ctx;
+  const { url, readySelector } = params;
+
+  await openAuthedPage(ctx, url, readySelector);
+
+  return {
+    found: true,
+    url: page.url(),
+    message: 'Reached authenticated content successfully.',
+  };
+}
+
+/**
+ * Navigate to an authenticated page and confirm we reached it — the canonical
+ * auth-handling pattern. Many SPAs resolve auth client-side a beat AFTER load and
+ * redirect to a login page, so we do NOT check the URL immediately. Instead we
+ * wait for the success signal (`readySelector`, an element that only renders for
+ * authenticated users). Only if that wait times out do we call `checkAuth()`: by
+ * then the URL has settled, so a login page becomes a clear AuthError (which the
+ * harness reports as `{ error: 'auth', message }`), while anything else re-throws
+ * as a genuine render timeout. The script never tries to log in itself.
+ *
+ * @param {object} ctx - The harness context.
+ * @param {string} url - The authenticated URL to load.
+ * @param {string} readySelector - Element proving authed content rendered.
+ * @returns {Promise<void>}
+ */
+async function openAuthedPage(ctx, url, readySelector) {
+  const { page, logger, timeout, checkAuth } = ctx;
+  const log = logger.child('navigate');
+  log.info(`Loading authenticated page ${url}`);
+  await page.goto(url, { waitUntil: 'domcontentloaded', timeout });
+  try {
+    await page.locator(readySelector).first().waitFor({ state: 'visible', timeout });
+    log.info('Authenticated content is present');
+  } catch (renderTimeout) {
+    await checkAuth(); // throws AuthError if the settled URL is a login page
+    throw renderTimeout;
+  }
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/examples/chained-workflow.mjs

@@ -0,0 +1,126 @@
+/**
+ * chained-workflow
+ *
+ * Demonstrates composing scripts: one script invokes another via
+ * `ctx.runChild`, reusing the same authenticated browser context. The child
+ * runs in-process and returns its result object directly.
+ *
+ * Here the parent collects a list of item URLs from an index page, then runs a
+ * child "fetch" script against each one. In a real project the child would be a
+ * separate script file imported at the top; it is inlined here so the example
+ * is self-contained.
+ */
+
+export const meta = {
+  name: 'chained-workflow',
+  description: 'Collect links from an index page, then fetch each via a child script.',
+  params: {
+    indexUrl: {
+      required: true,
+      description:
+        'Absolute URL of the index/listing page to scrape links from. Loaded as ' +
+        'the authenticated user.',
+      validate: /^https?:\/\/.+/,
+      invalidMessage: 'indexUrl must be an absolute http(s) URL.',
+    },
+    linkSelector: {
+      required: false,
+      default: 'a[href]',
+      description:
+        'CSS selector matching the links to follow on the index page. Defaults ' +
+        'to all anchors with an href.',
+    },
+    limit: {
+      required: false,
+      default: 3,
+      description:
+        'Maximum number of links to follow, to keep runs bounded. Provided as a ' +
+        'string on the CLI and coerced to a number.',
+      validate: (v) => Number(v) > 0 || 'limit must be a positive number',
+    },
+  },
+};
+
+/** A small child script run once per collected link. Normally its own file. */
+const fetchTitle = {
+  meta: {
+    name: 'fetch-title',
+    params: {
+      url: { required: true, validate: /^https?:\/\/.+/, invalidMessage: 'url must be absolute http(s)' },
+    },
+  },
+  /**
+   * Load a URL and return its document title.
+   *
+   * @param {object} ctx - The harness context (shares the parent's browser).
+   * @returns {Promise<object>} `{ url, title }`.
+   */
+  async execute(ctx) {
+    const { page, params, logger, timeout, checkAuth } = ctx;
+    logger.child('navigate').info(`Fetching ${params.url}`);
+    // domcontentloaded is enough here: the <title> is in the initial document.
+    await page.goto(params.url, { waitUntil: 'domcontentloaded', timeout });
+    await checkAuth();
+    return { url: page.url(), title: await page.title() };
+  },
+};
+
+/**
+ * Entry point. Collects links from the index, then fetches each via a child.
+ *
+ * @param {object} ctx - The harness context.
+ * @returns {Promise<object>} `{ found, count, results }`.
+ */
+export async function execute(ctx) {
+  const { params } = ctx;
+  const { indexUrl, linkSelector, limit } = params;
+
+  const links = await collectLinks(ctx, indexUrl, linkSelector, Number(limit));
+  const results = await fetchEach(ctx, links);
+
+  return { found: results.length > 0, count: results.length, results };
+}
+
+/**
+ * Load the index page and collect up to `limit` link URLs.
+ *
+ * @param {object} ctx - The harness context.
+ * @param {string} indexUrl - The listing page URL.
+ * @param {string} selector - Selector matching links to follow.
+ * @param {number} limit - Max links to return.
+ * @returns {Promise<string[]>} Absolute link URLs.
+ */
+async function collectLinks(ctx, indexUrl, selector, limit) {
+  const { page, logger, timeout, checkAuth } = ctx;
+  const log = logger.child('collect');
+  log.info(`Loading index ${indexUrl}`);
+  await page.goto(indexUrl, { waitUntil: 'domcontentloaded', timeout });
+  // Success signal: the links we intend to read are present. If they never
+  // appear, check auth (login redirects resolve late) before failing.
+  try {
+    await page.locator(selector).first().waitFor({ state: 'visible', timeout });
+  } catch (renderTimeout) {
+    await checkAuth();
+    throw renderTimeout;
+  }
+
+  const hrefs = await page.$$eval(selector, (els) => els.map((el) => el.href));
+  const unique = [...new Set(hrefs.filter(Boolean))].slice(0, limit);
+  log.info(`Collected ${unique.length} link(s)`);
+  return unique;
+}
+
+/**
+ * Run the child fetch script against each link, in sequence.
+ *
+ * @param {object} ctx - The harness context.
+ * @param {string[]} links - URLs to fetch.
+ * @returns {Promise<object[]>} One child result per link.
+ */
+async function fetchEach(ctx, links) {
+  const results = [];
+  for (const url of links) {
+    results.push(await ctx.runChild(fetchTitle, { url }));
+  }
+  return results;
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/examples/simple-fetch.mjs

@@ -0,0 +1,92 @@
+/**
+ * simple-fetch
+ *
+ * The minimal shape of an automation script: navigate to one page, confirm we
+ * are authenticated, and extract a piece of text. Use this as the starting
+ * template for single-page data extraction.
+ */
+
+export const meta = {
+  name: 'simple-fetch',
+  description: 'Navigate to a single page and extract its <h1> (demonstration script).',
+  params: {
+    url: {
+      required: true,
+      description:
+        'The absolute URL to load. Must include the scheme (https://). The page ' +
+        'is loaded as the authenticated user via injected Chrome cookies.',
+      validate: /^https?:\/\/.+/,
+      invalidMessage: 'url must be an absolute http(s) URL, e.g. "https://example.com".',
+    },
+    selector: {
+      required: false,
+      default: 'h1',
+      description:
+        'CSS selector for the element whose text to extract. Defaults to the ' +
+        'first <h1>. The longest matching element\'s text is returned.',
+    },
+    outputFile: {
+      required: false,
+      description:
+        'Optional absolute path. When set, the runner writes the extracted text ' +
+        'here instead of printing the result object.',
+      validate: /^\//,
+      invalidMessage: 'outputFile must be an absolute path (starting with "/").',
+    },
+  },
+};
+
+/**
+ * Entry point. Loads the page, verifies auth, and extracts the target text.
+ *
+ * @param {object} ctx - The harness context.
+ * @returns {Promise<object>} `{ found, url, content, outputFile }`.
+ */
+export async function execute(ctx) {
+  const { page, params } = ctx;
+  const { url, selector, outputFile } = params;
+
+  await loadPage(ctx, url, selector);
+  const content = await extractText(ctx, selector);
+
+  return { found: content !== null, url: page.url(), content, outputFile };
+}
+
+/**
+ * Load a URL and wait for the target element to render. Uses `domcontentloaded`
+ * (NOT `networkidle`, which is not a readiness signal) and then waits for the
+ * specific thing we need — the target selector. If that times out, we check auth:
+ * a login redirect (resolved late by many apps) surfaces as a clear AuthError,
+ * otherwise the render timeout is re-thrown.
+ *
+ * @param {object} ctx - The harness context.
+ * @param {string} url - Absolute URL to load.
+ * @param {string} selector - The element we expect to render (our success signal).
+ * @returns {Promise<void>}
+ */
+async function loadPage(ctx, url, selector) {
+  const { page, logger, timeout, checkAuth } = ctx;
+  const log = logger.child('navigate');
+  log.info(`Loading ${url}`);
+  await page.goto(url, { waitUntil: 'domcontentloaded', timeout });
+  try {
+    await page.locator(selector).first().waitFor({ state: 'visible', timeout });
+  } catch (renderTimeout) {
+    await checkAuth(); // throws AuthError if the settled URL is a login page
+    throw renderTimeout;
+  }
+}
+
+/**
+ * Extract the longest text matching a selector.
+ *
+ * @param {object} ctx - The harness context.
+ * @param {string} selector - CSS selector to read.
+ * @returns {Promise<string|null>} The text, or null if nothing matched.
+ */
+async function extractText(ctx, selector) {
+  const { utils, logger } = ctx;
+  const text = await utils.extractLongestText([selector], { minLength: 1 });
+  logger.child('extract').info(text ? `Got ${text.length} chars` : 'No match');
+  return text;
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/references/architecture.md

@@ -0,0 +1,61 @@
+# Architecture
+
+The system has six framework modules (in this skill's `scripts/`) plus the
+user's own scripts (in the project's configured scripts directory).
+
+## Components
+
+1. **`keyring.mjs`** — Reads Chrome's Safe Storage password from the OS keyring
+   (GNOME keyring) via the D-Bus Secret Service API. Pure JS (`dbus-next`), no
+   native deps, no Python. Exports `getChromeSafeStoragePassword()`.
+
+2. **`chrome-state.mjs`** — Reads cookies from Chrome's `Cookies` SQLite DB
+   (read-only; Chrome stays open), decrypts them with a PBKDF2 key derived from
+   the keyring password, and builds a Playwright `storageState` object. Exports
+   `extractCookies()`, `buildStorageState()`, `listProfiles()`.
+
+3. **`logger.mjs`** — Plain prefixed-line logger. `createLogger(prefix)` returns
+   `{ info, warn, error, child }`; `child(section)` extends the prefix.
+
+4. **`utils.mjs`** — `createUtils(page, logger)` builds the `ctx.utils` toolkit,
+   bound to the live page (modal dismissal, waits, text extraction, screenshot,
+   retry, …). See `ctx-api.md`.
+
+5. **`params.mjs`** — `resolveParams(meta, explicit, settings)` resolves params
+   in priority order and validates them, throwing `ParamError` on failure.
+
+6. **`harness.mjs`** — `runScript(script, params, options)`. Resolves/validates
+   params, extracts cookies, launches headless Chromium with the injected
+   storageState, builds `ctx`, runs `execute(ctx)` under an overall timeout, and
+   returns a result envelope. Defines `AuthError` and `ctx.checkAuth()`.
+
+7. **`run.mjs`** — CLI entry point. Parses `--key=value` args into harness
+   options vs. script params, loads compiled `settings.mjs`, imports the target
+   script by absolute path, prints resolved params, runs, reports, writes any
+   `outputFile`.
+
+## Data Flow
+
+```
+run.mjs
+  ├─ parse args → { params, options }
+  ├─ load settings.mjs → ctx.settings
+  ├─ import <script>.mjs
+  └─ runScript(script, params, { ...options, settings })
+        ├─ resolveParams(meta, params, settings)   ← validation gate
+        ├─ chrome-state.buildStorageState()
+        │     └─ keyring.getChromeSafeStoragePassword()
+        ├─ chromium.launch({ headless }) + newContext({ storageState })
+        ├─ build ctx { page, params, settings, logger, utils, checkAuth, runChild }
+        └─ script.execute(ctx) → result
+  └─ report result, write outputFile
+```
+
+## Result Envelope
+
+`runScript` always returns `{ success, ... }`:
+
+- success → `{ success: true, data: <script return value> }`
+- param failure → `{ success: false, error: 'params', message }`
+- auth failure → `{ success: false, error: 'auth', message, url, indicators }`
+- other failure → `{ success: false, error: 'script', message, stack }`

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/references/auth-and-sessions.md

@@ -0,0 +1,65 @@
+# Auth & Sessions
+
+Scripts run as the logged-in user without any manual login step, and without
+closing or controlling the user's running Chrome.
+
+## How auth works
+
+1. The harness reads the user's Chrome `Cookies` SQLite DB **read-only** — Chrome
+   can stay open; there is no lock conflict.
+2. Cookie values are encrypted. The harness fetches Chrome's "Safe Storage"
+   password from the OS keyring (GNOME keyring) over the D-Bus Secret Service
+   API, derives an AES key (PBKDF2, salt `saltysalt`, 1 iteration, SHA1, 16
+   bytes), and decrypts each cookie.
+   - **v10**: AES-128-CBC, IV = 16 spaces.
+   - **v11**: AES-128-CBC, IV embedded in bytes 3–18; strip a 16-byte random
+     prefix from the decrypted plaintext.
+3. Decrypted cookies become a Playwright `storageState`, injected into a fresh
+   headless context. The browser is now authenticated as the user.
+
+This is all local. Nothing leaves the machine. No Python; pure JS via
+`dbus-next`, `better-sqlite3`, and Node's `crypto`.
+
+## Choosing the profile
+
+The Chrome profile defaults to `Default`. Override per run with
+`--profileName="Profile 1"`, or set a project default in settings
+(`chromeProfile`) so it flows in via `ctx.settings`.
+
+## Detecting auth failures
+
+Cookies expire; SSO sessions lapse. After each navigation a script should call
+`await ctx.checkAuth()`. It inspects the current URL for login indicators
+(`/login`, `/sso`, `multipass`, `accounts.google.com`, etc.) and throws an
+`AuthError` if found.
+
+The harness catches `AuthError` and returns:
+
+```
+{ success: false, error: 'auth', message, url, indicators }
+```
+
+The `message` is actionable and meant to reach the user verbatim. A sub-agent
+returns it to the orchestrator, which relays it:
+
+> Authentication required... Log in to the target site in your Chrome browser
+> (profile: "Default"), then retry this script.
+
+## The retry contract
+
+There is no mid-script recovery. On an auth failure:
+
+1. The message reaches the user, who logs into the site in their Chrome profile.
+2. Re-run the **same** command. The harness re-reads the now-valid cookies.
+
+A sub-agent cannot wait for a login, so it stops at step 1 and reports; the
+orchestrator relays the message and dispatches the re-run.
+
+Never attempt to script the login itself, and never weaken `checkAuth` to get
+past a login wall.
+
+## Scope cookie extraction
+
+Extraction can be limited to domain substrings for speed/privacy. The harness
+`domains` option (and `extractCookies(profile, domains)`) filters
+`host_key LIKE '%domain%'`. Leave null to extract all cookies.

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/references/ctx-api.md

@@ -0,0 +1,96 @@
+# The `ctx` API
+
+Every script's `execute(ctx)` receives a single context object. Destructure what
+you need at the top of each function.
+
+## Core members
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `ctx.page` | `Page` | Playwright page. Primary interaction surface. |
+| `ctx.context` | `BrowserContext` | The browser context (cookies already injected). |
+| `ctx.browser` | `Browser` | The Chromium instance. |
+| `ctx.params` | object | Fully resolved + validated params. |
+| `ctx.settings` | object | Compiled project settings (from `settings.mjs`). |
+| `ctx.timeout` | number | Overall timeout (ms); use for `goto`/wait calls. |
+| `ctx.logger` | Logger | Prefixed logger (see below). |
+| `ctx.utils` | object | Generic action helpers (see below). |
+| `ctx.debug` | object | Exploration & debugging tools (see below). |
+| `ctx.checkAuth()` | fn | Throws `AuthError` if the current URL looks like a login page. Call after every navigation. |
+| `ctx.runChild(script, params)` | fn | Run another script module in the same browser context; returns its result. Child gets its own resolved params, logger, and utils. |
+
+## `ctx.logger`
+
+Plain prefixed lines. `info` → stdout; `warn`/`error` → stderr, tagged.
+
+```js
+const log = ctx.logger.child('navigate');   // prefix: [script-name:navigate]
+log.info('Loading repo');                    // [script-name:navigate] Loading repo
+log.warn('modal not found, using Escape');   // [script-name:navigate] WARN ...
+```
+
+## `ctx.utils`
+
+Built per-run, bound to the live `page` and the script's logger. All are async
+unless noted.
+
+| Helper | Signature | Description |
+|--------|-----------|-------------|
+| `autoDismiss` | `(triggerLocator, dismiss)` | **Preferred** modal handling: register a `page.addLocatorHandler` so `dismiss` runs whenever `triggerLocator` blocks an action. Timing-independent — no sleeps, no races. Use for any modal/banner that may appear asynchronously. |
+| `dismissModals` | `(selectors, { timeout? })` | One-shot best-effort dismissal of modals KNOWN to be present already. Clicks the first of each candidate selector that currently exists; no fixed delays. For async modals, use `autoDismiss`. |
+| `clickByText` | `(text, { force?, timeout? })` | Wait for and click the first element matching `text` (RegExp or string). `force` defaults **false** (auto-waits for actionability). |
+| `waitForText` | `(text, { timeout? })` | Wait for text to appear; does not click. |
+| `extractLongestText` | `(selectors, { minLength? })` | Longest `textContent` across candidate selectors meeting `minLength`, or null. |
+| `extractTextByPattern` | `(pattern, { source?, group? })` | First regex match from page body (or supplied `source`); returns trimmed match or null. |
+| `screenshot` | `(path, { fullPage? })` | Save a debug screenshot. Failures are logged, never thrown. |
+| `scrollIntoView` | `(selector)` | Scroll matching element into view; returns boolean found. |
+| `retry` | `(fn, { attempts?, delay?, label? })` | Retry an async fn; throws the last error if exhausted. |
+
+### On `force` clicks
+
+Non-forced clicks are the resilient default: Playwright auto-waits for the element
+to be visible, stable, and not covered before clicking — which naturally waits out
+overlays and transitions. `force: true` bypasses those checks and is fire-and-forget
+(it can "succeed" while landing on nothing), so reserve it for the rare element a
+component library (e.g. Blueprint.js) wrongly reports as disabled — and verify the
+outcome with a follow-up wait. There is no `waitForSPA` helper: do not wait on
+`networkidle` as a readiness signal (see `script-conventions.md` → Waits); wait for
+the specific element/text you need instead.
+
+## `ctx.debug`
+
+Tools for **observing the real page** so you build waits and selectors from facts,
+not guesses. Conventions require observing a page before automating it
+(`script-conventions.md` → "observe the real page"); these are how. Built per-run,
+bound to the live `page`/`logger`. All are async and none throw (a debug aid must
+never break a run). Artifacts are written under `ctx.debug.dir` (a unique per-run
+directory under the OS temp dir, created lazily on first write).
+
+| Tool | Signature | Description |
+|------|-----------|-------------|
+| `screenshot` | `(name?, { fullPage? })` | Save a PNG; returns its path (or null). |
+| `html` | `(name?)` | Save the current page HTML; returns its path. |
+| `dump` | `(name?)` | Full snapshot — URL, title, visible text, screenshot, HTML — to the debug dir; returns `{ dir, url, title, files, textPreview }`. The go-to "what does this page look like right now?" tool. |
+| `describe` | `(selector, { limit? })` | What a CSS selector matches: `{ count, elements[] }` with tag/role/id/classes/text/visibility/href. Fastest way to check a selector is right. |
+| `count` | `(selector)` | Number of matches. |
+| `clickables` | `({ limit? })` | List visible interactive elements (anchors, buttons, role buttons/tabs/links, onclick). Use when the obvious `<a>`/button doesn't exist and the real control is a click-handled div. |
+| `findText` | `(pattern, { limit? })` | Where does this text live? For each match, the owning element AND its clickable ancestor — i.e. *what to click* to act on that text. Matches text on an element's own text nodes (works even when the element also has icon/element children). |
+| `watch` | `(fn, { samples?, intervalMs?, label? })` | Sample a browser-side metric over time and log how it evolves. Answers "WHEN is this ready?" — e.g. `watch(() => document.body.innerText.length)` exposes that `networkidle` fired on an empty shell. Returns `[{ t, value }]`. |
+| `dir` | getter | Absolute path to this run's artifact directory. |
+
+### Auto-capture on failure
+
+When a script throws an unexpected error, the harness automatically runs
+`debug.dump('failure')` before closing the browser and reports the directory in the
+result (`result.debugDir`, printed by the runner). So a failed run leaves a
+screenshot, HTML, and text snapshot of the exact failing state with no extra code.
+
+### The intended workflow
+
+1. Stuck on a selector or timing? `await ctx.debug.dump()` and look at the files.
+2. Selector returning nothing? `describe(it)` / `clickables()` / `findText(text)`
+   to discover the real element (and its clickable ancestor).
+3. Wait firing too early/never? `watch(() => <metric>)` to find the moment the
+   page is genuinely ready, then wait on that concrete signal.
+4. Remove debug calls (or leave a couple of cheap ones) once the script is solid;
+   `dump`/`screenshot`/`html` write files, so don't leave those in hot loops.