@sous-io/sous 0.1.0 → 0.2.0

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

@@ -1,92 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-# 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

@@ -1,65 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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.

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

@@ -1,104 +0,0 @@
-# Installation
-
-## Runtime & platform
-
-- Node.js ≥ 22.
-- Linux with a GNOME-keyring-compatible Secret Service (the user's Chrome must
-  have stored its Safe Storage key there — true after Chrome has run once on a
-  desktop session with an unlocked keyring).
-- Google Chrome installed with at least one profile the user has logged into.
-
-macOS (Keychain) and Windows (DPAPI) are not yet supported by `keyring.mjs`.
-
-## Dependencies
-
-The runner and harness import these at runtime; the framework does not bundle
-them. Install them **at the consuming project's root** — NOT globally.
-
-Why not global: the scripts use ESM `import 'playwright'`. ESM resolves bare
-imports by walking *up* the directory tree from the importing file looking for a
-`node_modules`. The compiled runner lives at
-`<projectRoot>/.claude/skills/about-automated-browser-tasks/scripts/run.mjs`, so a
-`node_modules` at `<projectRoot>` is found by walking up; a global npm install is
-never on that resolution path.
-
-```bash
-cd <projectRoot>        # the repo root that contains .claude/skills/
-npm install playwright better-sqlite3 dbus-next
-npx playwright install chromium
-```
-
-Add a `package.json` at `<projectRoot>` if none exists (`{"type":"module","private":true}`)
-and gitignore `node_modules/`.
-
-- `playwright` — headless browser automation.
-- `better-sqlite3` — reads Chrome's `Cookies` SQLite DB.
-- `dbus-next` — pure-JS D-Bus client for the keyring (no Python, no native build).
-
-Tested with: Playwright 1.61, better-sqlite3 12.x, Node 22, Chrome cookie format
-v11, Ubuntu 22.04.
-
-## Project wiring (via sous)
-
-A downstream project compiles this bundle into its skills directory and compiles
-`settings.tpl.mjs` → `settings.mjs` (sibling of `run.mjs`) so scripts get
-`ctx.settings`. Example compilation targets:
-
-```js
-compilation: {
-  targets: [
-    {
-      // The skills (SKILL.tpl.md, references, examples, scripts) → skills dir
-      entryGlob: "${sousRootPath}/shared-prompts/skills/automated-browser-tasks/**/*",
-      outputs: [{ destinationDir: "${projectRoot}/.claude/skills" }],
-    },
-  ],
-}
-```
-
-Define project values (`chromeProfile`, base URLs, resource IDs, …) in `_vars`. The
-`{% exportScalarVarsJs %}` tag in `settings.tpl.mjs` emits all in-scope scalars
-as the runtime settings module — no per-key wiring needed. Be sure to define
-`browserAutomationScriptsDir` (the absolute path to the project's task scripts)
-in `_vars` — both the runtime and the task manifest below rely on it.
-
-## Task manifest in core memory
-
-So the agent always knows which browser tasks exist (without relying on a skill
-trigger firing), render the shared memory partial into the project's memory source
-tree, then `@include` it from a core-memory file. It renders a live list of every
-task script via `{% getFiles … import="meta" %}`, reading each script's `meta`.
-
-`@include` does NOT substitute variables, so you cannot `@`-include the shared
-`INDEX.tpl.md` by an absolute `${...}` path. Instead, add a compilation target that
-renders it into your memory tree (exactly how `runtimeContext` emits
-`session-context.md`):
-
-```js
-// A target that renders the shared manifest into the project's memory source.
-const browserTaskManifest = {
-  entryPoint: "${sousRootPath}/shared-prompts/memories/automated-browser-tasks/INDEX.tpl.md",
-  outputs: [
-    { destinationFile: "${memoryRoot}/tools/automated-browser-tasks.md" },
-  ],
-};
-```
-
-Order this target BEFORE the memories target that composes core memory. Then pull
-it into a memory file (e.g. `tools/README.md`) with a plain relative Sous include:
-put an `@`-prefixed line containing just the rendered filename
-(`automated-browser-tasks.md`) on its own line in that file.
-
-The manifest auto-rebuilds on every `xcv build`, so newly created tasks appear
-automatically. It requires `browserAutomationScriptsDir` to be in scope (the
-absolute path to the task scripts).
-
-## Verifying
-
-Run any example script by absolute path:
-
-```bash
-node <scriptsDir>/run.mjs <scriptsDir>/../examples/simple-fetch.mjs --url=https://example.com
-```
-
-A clean run prints extracted cookie counts, a browser-ready line, and the result.

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

@@ -1,243 +0,0 @@
-# Script Conventions
-
-These rules are non-negotiable. A reviewer (or linter) should be able to reject a
-script that violates them.
-
-## Quality bar: bulletproof or it doesn't ship
-
-A flaky script is a broken script. "Works most of the time" is failure. Write for
-100% reliability across many consecutive and parallel runs from the first draft —
-do not ship something that "usually works" and plan to harden later.
-
-The single greatest source of flakiness is **guessing about timing instead of
-waiting for facts**. Every wait must key off a concrete, observable condition that
-*proves* the thing you need is ready. Spend the extra time to find that signal.
-Arbitrary delays (`waitForTimeout`) are the enemy — see [Waits](#waits); they are
-effectively banned.
-
-Before writing a single wait or selector, **observe the real page.** Do not assume
-DOM structure. Build your waits from what you actually see — selectors invented
-from imagination are how you get a script that passes once and fails in CI.
-
-`ctx.debug` exists for exactly this (full surface in `ctx-api.md`):
-
-- `ctx.debug.dump()` — snapshot URL, title, text, screenshot, and HTML to disk.
-- `ctx.debug.describe(selector)` / `ctx.debug.clickables()` — see whether a
-  selector matches and what the real interactive elements are (often a
-  click-handled `div`, not the `<a>`/`<button>` you assumed).
-- `ctx.debug.findText(text)` — locate text and the clickable ancestor to target.
-- `ctx.debug.watch(() => metric)` — sample a metric over time to find the *moment*
-  the page is genuinely ready (this is how you discover that `networkidle` fired
-  on an empty shell), then wait on that concrete signal.
-
-On an unexpected throw, the harness auto-captures a failure snapshot
-(`result.debugDir`) — check it first when a run fails. Remove file-writing debug
-calls (`dump`/`screenshot`/`html`) once the script is solid; keep them out of hot
-loops.
-
-## Structure
-
-`execute(ctx)` is a thin orchestrator that reads like a table of contents. All
-real work lives in small, named step functions defined below `execute` in the
-same file.
-
-- One discrete action per step function (navigate, dismiss, extract, parse…).
-- ≤ 30 lines per function; 10 or fewer is ideal.
-- Module-level functions, not class methods.
-- Generic patterns → `ctx.utils`. Site-specific patterns → step functions (which
-  a project may later factor into shared libs it imports).
-
-## Doc-blocks
-
-EVERY function — `execute` included — has a proper JSDoc block: a description
-line plus `@param` for every argument and `@returns`. Use
-`@returns {Promise<void>}` for functions that return nothing. Single-line
-`/** … */` comments are NOT sufficient.
-
-## Destructuring
-
-Each function destructures the members it needs off `ctx` (and off `params`) at
-the top of its body, so the body never repeats `ctx.`/`params.` prefixes:
-
-```js
-async function navigateToRepo(ctx, baseUrl, repoId) {
-  const { page, logger, timeout, checkAuth } = ctx;
-  ...
-}
-```
-
-## Params (`meta.params`)
-
-The framework resolves and validates params before `execute` runs. Scripts never
-validate their own params. Resolution priority (low → high):
-`ctx.settings` < `meta.params[x].default` < explicit (CLI) params.
-
-Each param spec:
-
-| Field | Type | Meaning |
-|-------|------|---------|
-| `required` | boolean | Error if nothing resolves. |
-| `default` | any | Fallback value. |
-| `description` | string | Be genuinely descriptive: what it is, where to find it, how it's used, consequence of omitting. Shown in listings and errors. |
-| `validate` | `RegExp` \| `Function` | See below. |
-| `invalidMessage` | string | Error for a failing RegExp, or a `validate` fn returning `false`. |
-
-`validate`:
-- **RegExp** — resolved value (as string) must match.
-- **Function** `(value, resolvedParams) => true | false | string` — `true` valid;
-  a returned `string` is used as the error; `false` falls back to `invalidMessage`.
-  The function gets all resolved params, enabling cross-param checks.
-
-All failures across params are collected into one `ParamError`.
-
-## Logging
-
-Use `ctx.logger`, never `console.log`. Create a child per section:
-`const log = ctx.logger.child('navigate')`. Output is
-`[script-name:section] message`. Levels: `info`, `warn`, `error`.
-
-## Return shape
-
-Return a plain object. Common keys:
-
-- `found: boolean` — whether the target content was located.
-- `content: string` — extracted content (when found).
-- `outputFile: string` — path for the runner to write `content` to.
-- a URL key (e.g. `buildUrl`) — where content was found.
-- `message: string` — human-readable explanation, especially on failure.
-
-On `found: false`, include diagnostics (`pageTextPreview`, `message`).
-
-## Verify every action
-
-Do not assume an action took effect — prove it. After every navigation or click
-that changes state, wait for a signal that confirms the *intended outcome*:
-
-- After a navigation: `await page.waitForURL(/expected-path/)`, or wait for an
-  element that only exists on the destination.
-- After a click that should open a view: wait for that view's content, not just
-  for the click to return.
-- After triggering content load: wait for the content to be present AND non-empty
-  (e.g. a `<pre>` whose text length exceeds a threshold), not merely attached.
-
-A click with `{ force: true }` is fire-and-forget: it bypasses Playwright's
-actionability checks (visible, stable, not covered) and reports success even when
-it lands on nothing. Prefer a plain click — Playwright then auto-waits for the
-element to be actionable, which naturally waits out overlays and transitions.
-Reserve `force` for the rare element a component library wrongly reports as
-disabled, and even then verify the outcome afterward.
-
-## Error handling
-
-Throw on unexpected failures; the harness catches and reports. Never
-catch-and-continue to paper over a problem. Auth failures come from
-`ctx.checkAuth()`; page-interaction failures (missing element, timeout) should
-propagate naturally. Fix root causes, not symptoms.
-
-**Auth resolves late in SPAs.** A single-page app often loads its shell, *then*
-decides client-side that the session is invalid and redirects to a login page a
-beat later. So:
-- Do NOT call `ctx.checkAuth()` immediately after `goto` — the redirect may not
-  have happened yet (false pass) and the URL may not have settled.
-- Do NOT race the success signal against the login URL — a valid session can
-  *transiently* touch a login-ish URL before bouncing back (false fail).
-- DO wait for your success signal (the authenticated view's element). Only if that
-  times out, *then* call `ctx.checkAuth()` — by then the URL has settled, so a
-  login page is a real `AuthError` and anything else is a genuine render timeout.
-
-## Naming
-
-- Files: `verb-noun-qualifier.mjs` (e.g. `get-repo-ci-error.mjs`).
-- Step functions: `verbNoun` camelCase (`navigateToRepo`, `dismissModals`).
-- Log sections: short, lowercase, no spaces (`navigate`, `dismiss`, `extract`).
-
-## Waits
-
-Wait for **specific, verifiable things** — never for time. This is the rule that
-makes scripts bulletproof.
-
-### `waitForTimeout` is effectively banned
-
-A fixed sleep is a bet that something will be ready by then. The bet loses
-intermittently — that is precisely what flakiness *is*. Exhaust every avenue for a
-condition-based wait before even considering a sleep:
-
-1. Wait for an element/state that proves readiness (`locator.waitFor`,
-   `page.waitForURL`, `expect(locator).toBeVisible()`).
-2. Wait for a content predicate via `page.waitForFunction(() => …)` when readiness
-   is "the data populated", not just "an element exists".
-3. Wait for a network response (`page.waitForResponse`) when the DOM gives no
-   signal but a known request does.
-4. Install a handler for interrupting UI (`page.addLocatorHandler`, below) instead
-   of sleeping to "let a modal pass".
-
-Only if ALL of these are genuinely impossible may you fall back to
-`page.waitForTimeout` — and then you must (a) keep it short, (b) write a comment
-explaining what DOM-observable signal you searched for and why none exists, and
-(c) feel bad about it. Treat each one as a defect to be removed later. A script
-should aim for **zero** `waitForTimeout` calls.
-
-### `networkidle` is NOT a readiness signal
-
-`waitForLoadState('networkidle')` means "the network went quiet", which in a
-modern SPA happens long before — or long after — the content you want renders.
-A large SPA commonly hits network idle while the DOM is still an empty ~600-char
-shell, with every real value still to be fetched and rendered client-side. Never
-treat `networkidle` as "the page is ready". Wait for the *specific element or
-text* you need instead. Use `domcontentloaded` for the initial `goto`, then a
-concrete element wait.
-
-### Pick a signal that proves the exact thing you need
-
-- "Tab bar loaded" → wait for a specific named tab to be visible.
-- "List rendered" → wait for a row's distinguishing text (e.g. a commit hash
-  pattern), not a generic container that exists while empty.
-- "Log loaded" → wait for the log element AND a length/content predicate, so an
-  empty placeholder doesn't satisfy the wait.
-
-### Virtualized lists/grids → set a tall viewport, don't scroll-accumulate
-
-A virtualized list or grid renders only the rows within the scroll viewport (a
-31-row table may put only ~17 rows in the DOM). A single DOM sweep then
-silently returns a partial set. The cheap, robust fix is to enlarge the viewport
-BEFORE navigating, so the grid materializes every row at once:
-
-```js
-await page.setViewportSize({ width: 1600, height: 20000 }); // then goto()
-```
-
-This overrides the harness's default 1920×1080 per-page and needs no harness change.
-Prefer it over a scroll-accumulate loop: far less code, no timing loop. Then **verify
-completeness** — extract the count the UI advertises (e.g. a "Properties 31" header
-badge) and assert the extracted row count equals it, so a clipped read fails loud
-instead of returning a silent subset. A tall viewport is not universal: a virtualizer
-bounded by its own container's fixed CSS height can still clip regardless of window
-size — the assertion is what catches that, and scroll-accumulate is the fallback.
-
-### Unpredictable interrupting UI → `addLocatorHandler`, not sleeps
-
-Modals/banners that appear at an unpredictable moment (welcome dialogs, "what's
-new", cookie prompts) are a classic flake source: dismiss-then-continue races the
-modal's appearance. Register a handler once; Playwright auto-runs it whenever that
-element would block an action — fully timing-independent:
-
-```js
-await page.addLocatorHandler(
-  page.getByRole('dialog').filter({ has: page.getByRole('button', { name: 'Close' }) }),
-  async (dialog) => { await dialog.getByRole('button', { name: 'Close' }).click(); }
-);
-```
-
-### Timeouts
-
-Pass `ctx.timeout` to waits rather than hardcoding numbers, so a slow environment
-can be accommodated centrally. A generous timeout on a *correct* condition is
-fine — it only ever waits as long as it must, then proceeds the instant the
-condition holds. That is the opposite of a fixed sleep.
-
-### Prefer robust locators
-
-Favor role/text/label locators (`getByRole`, `getByText`, `getByLabel`) and stable
-attributes (`data-testid`) over brittle CSS/class chains — component-library class
-names (`bp6-…`) change between versions. When the only distinguishing feature is
-visible text, a text/regex locator is more durable than a guessed class.