dsh-tabbit 0.2.0

package/skills/tabbit-browser/references/playwright-recipes.md

@@ -0,0 +1,350 @@
+# Playwright recipes
+
+Use these recipes inside a `tabbit-cli nodejs --task '<name>'` heredoc.
+Each code block is an async function body: use it
+directly without adding an async wrapper.
+
+## Contents
+
+- Navigate and inspect
+- Inspect visible controls and visual targets
+- Work with canvas-backed rich editors
+- Fill and submit a form
+- Extract and aggregate data
+- Handle a popup or a possible popup
+- Handle same-tab or new-tab navigation
+- Handle JavaScript dialogs
+- Work with iframes
+- Download and upload files
+- Repeat actions safely
+- Capture evidence
+- Correct common API mistakes
+
+## Navigate and inspect
+
+Wait for page content that establishes readiness rather than sleeping for a
+fixed duration.
+
+```js
+await page.goto("https://example.com", {waitUntil: "domcontentloaded"});
+const heading = page.getByRole("heading").first();
+await heading.waitFor({state: "visible", timeout: 15000});
+return {
+  url: page.url(),
+  title: await page.title(),
+  heading: (await heading.innerText()).trim(),
+};
+```
+
+Use `mutation: "possible"` because navigation changes browser state.
+
+## Inspect visible controls and visual targets
+
+Use native Playwright. Prefer semantic locators when the target is known. For a
+broad view, request an AI-mode ARIA snapshot and bound what you return:
+
+```js
+const snapshot = await page.ariaSnapshot({mode: "ai", depth: 20, boxes: true});
+return snapshot.slice(0, 6000);
+```
+
+Use a fresh snapshot ref with `page.locator("aria-ref=e12")`. For iframe refs,
+Playwright accepts the returned `f1e2` form. Use a new snapshot after navigation
+or a substantial render. For canvas or coordinate-only surfaces, use native
+`page.mouse` operations; the evaluation receipt automatically records compact
+cross-frame and open-shadow-root hit diagnostics for mouse clicks.
+
+## Work with canvas-backed rich editors
+
+Canvas-backed editors often keep usable toolbar buttons and editor state in the
+accessibility tree even when their visible DOM is flat or misleading. Inspect
+that tree before using coordinates:
+
+```js
+const before = await page.ariaSnapshot({mode: "ai", depth: 20, boxes: true});
+return before.slice(0, 6000);
+```
+
+Use a ref from that snapshot directly. ARIA refs may include a frame prefix such
+as `f1e2`; native Playwright resolves either form:
+
+```js
+await page.locator("aria-ref=e12").click();
+return (await page.ariaSnapshot({mode: "ai", depth: 20})).slice(0, 6000);
+```
+
+Take a new snapshot after each editor mode change because the next ARIA snapshot
+replaces the old ref set. Check state flags such as `[pressed]`, `[expanded]`,
+`[checked]`, and `[active]`. After inserting a table, verify that the active
+textbox for following content is outside the `table` subtree before typing. Use
+a screenshot only when the ARIA tree and visible surface still disagree.
+
+## Fill and submit a form
+
+Prefer labels and roles. Verify the resulting application state.
+
+```js
+await page.getByLabel("Email").fill("user@example.com");
+await page.getByLabel("Password").fill("correct horse battery staple");
+
+await Promise.all([
+  page.waitForURL(/dashboard/, {timeout: 15000}),
+  page.getByRole("button", {name: /sign in/i}).click(),
+]);
+
+const heading = page.getByRole("heading", {name: /dashboard/i});
+await heading.waitFor({state: "visible"});
+return {url: page.url(), signedIn: true};
+```
+
+If submission does not necessarily navigate, remove `waitForURL` and wait for a
+success message or changed application element instead.
+
+## Extract and aggregate data
+
+Use locators for ordinary lists and tables. Aggregate inside the runtime rather
+than returning an entire DOM snapshot.
+
+```js
+const rows = page.getByRole("table").getByRole("row");
+const count = await rows.count();
+const records = [];
+
+for (let index = 1; index < count; index += 1) {
+  const cells = rows.nth(index).getByRole("cell");
+  records.push({
+    name: (await cells.nth(0).innerText()).trim(),
+    status: (await cells.nth(1).innerText()).trim(),
+  });
+}
+
+const activeNames = records
+  .filter((record) => record.status === "Active")
+  .map((record) => record.name);
+return {rowCount: records.length, activeNames};
+```
+
+For a large DOM-only computation, use one `page.evaluate()` and return an
+aggregate. Pass data through the argument channel instead of relying on Node
+closures:
+
+```js
+const minimum = 100;
+return await page.evaluate(({minimum}) => {
+  const values = [...document.querySelectorAll("[data-price]")]
+    .map((element) => Number(element.getAttribute("data-price")));
+  return {
+    count: values.length,
+    aboveMinimum: values.filter((value) => value >= minimum).length,
+  };
+}, {minimum});
+```
+
+## Handle a popup or a possible popup
+
+When a popup is expected, install the waiter before clicking:
+
+```js
+const opener = page.getByRole("link", {name: /details/i});
+const [popup] = await Promise.all([
+  context.waitForEvent("page", {timeout: 15000}),
+  opener.click(),
+]);
+await popup.waitForLoadState("domcontentloaded");
+usePage(popup);
+
+const result = {title: await page.title(), url: page.url()};
+await page.close();
+usePage(pages().find((candidate) => !candidate.isClosed()));
+return result;
+```
+
+When a popup is only one possible outcome, start a bounded waiter and inspect
+both outcomes. Retain the original page explicitly:
+
+```js
+const original = page;
+const beforeUrl = original.url();
+const popupPromise = context
+  .waitForEvent("page", {timeout: 8000})
+  .catch(() => null);
+
+await original.getByRole("link", {name: /open report/i}).click();
+const popup = await popupPromise;
+
+if (popup) {
+  await popup.waitForLoadState("domcontentloaded");
+  const evidence = {kind: "popup", title: await popup.title(), url: popup.url()};
+  await popup.close();
+  usePage(original);
+  return evidence;
+}
+
+await original.waitForLoadState("domcontentloaded").catch(() => {});
+return {
+  kind: original.url() === beforeUrl ? "in-page" : "same-tab",
+  title: await original.title(),
+  url: original.url(),
+};
+```
+
+Do not click first and install `waitForEvent("page")` afterward; the event may
+already have fired.
+
+## Handle same-tab or new-tab navigation
+
+Use native Playwright and install the waiter before the action:
+
+```js
+await Promise.all([
+  page.waitForURL(/\/orders\/\d+$/),
+  page.getByRole("button", {name: /create order/i}).click(),
+]);
+return {title: await page.title(), url: page.url()};
+```
+
+For a popup, pair `context.waitForEvent("page")` with the click. Receipts report
+new pages but do not replace the active `page`. Do not replace the requested
+click with `page.goto(linkHref)`; that can skip application behavior. Close
+obsolete task-created pages with native `popup.close()`.
+
+## Handle JavaScript dialogs
+
+Attach the handler before the triggering action. Dialog callbacks must not be
+left pending because they block page JavaScript.
+
+```js
+let message = null;
+page.once("dialog", async (dialog) => {
+  message = dialog.message();
+  await dialog.accept();
+});
+await page.getByRole("button", {name: /delete/i}).click();
+await page.getByText(/deleted/i).waitFor({state: "visible"});
+return {accepted: true, message};
+```
+
+Use `dialog.dismiss()` when cancellation is the requested behavior.
+
+## Work with iframes
+
+Use `frameLocator()` instead of trying to query iframe contents from the parent
+document.
+
+```js
+const payment = page.frameLocator('iframe[title="Payment"]');
+await payment.getByLabel("Card number").fill("4242 4242 4242 4242");
+await payment.getByRole("button", {name: /pay/i}).click();
+await page.getByText(/payment complete/i).waitFor({state: "visible"});
+return {paid: true};
+```
+
+## Download and upload files
+
+Install the download waiter before clicking and save into the task artifact
+directory:
+
+```js
+const [download] = await Promise.all([
+  page.waitForEvent("download", {timeout: 15000}),
+  page.getByRole("button", {name: /export/i}).click(),
+]);
+const output = artifactPath("export.csv");
+await download.saveAs(output);
+return {
+  artifact: output,
+  suggestedFilename: download.suggestedFilename(),
+  failure: await download.failure(),
+};
+```
+
+Chromium's built-in PDF viewer may open a page without emitting a download.
+Fetch the rendered link through the BrowserContext request client, validate the
+signature, and save it as an artifact:
+
+```js
+const link = page.getByRole("link", {name: /view pdf/i});
+const pdfUrl = new URL(await link.getAttribute("href"), page.url()).href;
+const response = await context.request.get(pdfUrl);
+assert(response.ok(), `PDF request failed: ${response.status()}`);
+const body = await response.body();
+assert.equal(body.subarray(0, 5).toString(), "%PDF-");
+const output = artifactPath("paper.pdf");
+await (await import("node:fs/promises")).writeFile(output, body);
+return {artifact: output, bytes: body.length, url: pdfUrl};
+```
+
+For a normal file input, use `setInputFiles()`:
+
+```js
+await page.getByLabel("Upload document").setInputFiles("/absolute/input.pdf");
+await page.getByText(/upload complete/i).waitFor({state: "visible"});
+return {uploaded: true};
+```
+
+For a file chooser opened by a button:
+
+```js
+const [chooser] = await Promise.all([
+  page.waitForEvent("filechooser"),
+  page.getByRole("button", {name: /choose file/i}).click(),
+]);
+await chooser.setFiles("/absolute/input.pdf");
+await page.getByText(/upload complete/i).waitFor({state: "visible"});
+return {uploaded: true};
+```
+
+## Repeat actions safely
+
+Re-resolve locators each iteration because frameworks may replace DOM nodes.
+Verify progress and bound every loop.
+
+```js
+const clicked = [];
+for (let index = 0; index < 5; index += 1) {
+  const items = page.getByRole("list", {name: /news/i}).getByRole("link");
+  assert.ok(await items.count() > index, `missing news item ${index + 1}`);
+  const item = items.nth(index);
+  const title = (await item.innerText()).trim();
+
+  const original = page;
+  const [popup] = await Promise.all([
+    context.waitForEvent("page", {timeout: 10000}),
+    item.click(),
+  ]);
+  await popup.waitForLoadState("domcontentloaded");
+  clicked.push({title, landingTitle: await popup.title(), url: popup.url()});
+  await popup.close();
+  usePage(original);
+}
+return {count: clicked.length, clicked};
+```
+
+If the page can reorder after each click, locate by captured title rather than
+by index. Never use an unbounded loop waiting for a page condition.
+
+## Capture evidence
+
+Use a plain filename with `artifactPath()`:
+
+```js
+const output = artifactPath("final-state.png");
+const screenshot = await page.screenshot({path: output, fullPage: true});
+return {screenshot, title: await page.title(), url: page.url()};
+```
+
+Take screenshots as evidence or when visual state matters, not as the default
+way to discover ordinary DOM controls.
+
+## Correct common API mistakes
+
+| Incorrect | Correct |
+| --- | --- |
+| `browser.pages()` | `context.pages()` or `pages()` |
+| `document.querySelector(...)` in the Node body | `page.evaluate(() => document.querySelector(...))` |
+| `expect(locator).toHaveValue(...)` | `await expect(locator).toHaveValue(...)` with the official Playwright Test `expect` |
+| `page.waitForTimeout(3000)` after every action | wait for a locator, URL, event, response, or load state |
+| click, then `waitForEvent("page")` | install the event waiter before the click with `Promise.all` |
+| return a Locator/Page/JSHandle | return a small JSON-safe object |
+| `page.goto(href)` when asked to click | call `locator.click()` and verify its result |
+| create a new browser for the next step | reuse the same task and persistent `page`/`context` |

package/skills/tabbit-browser/references/runtime-recovery.md

@@ -0,0 +1,95 @@
+# Runtime receipts and recovery
+
+Read this reference when an evaluation is queued, running, interrupted, timed
+out, quarantined, or returns a resource handle.
+
+## Receipt states
+
+Every evaluation is serialized and identified by `requestId`.
+
+- `succeeded`: use `result.value` or its resource handle.
+- `failed`: inspect the error and correct the code only when no uncertain
+  mutation remains.
+- `queued` or `running`: the operation is still live. Run `tabbit-cli
+  receipt --task '<name>' --request '<request-id>'`; do not submit the operation
+  again.
+- `interrupted` with `mutationState: "possible"`: the action may already have
+  happened. Do not retry it under any request ID.
+
+The CLI wait window controls how long the call waits for a receipt. Its expiry
+is not an operation failure.
+
+## Interrupted mutation procedure
+
+1. Read the named task's receipt with the same request ID.
+2. If still queued or running, continue polling the same receipt.
+3. Run `tabbit-cli checkpoint --task '<name>'` after it settles. Check
+   `url`, `pageCount`,
+   `targetEpoch`, `documentGeneration`, and `mainFrameAttached`.
+4. Inspect the application state with a new read-only evaluation.
+5. Continue from observed state. Retry only when evidence proves the original
+   mutation did not occur.
+
+Never clear uncertainty by switching browser automation backends. Within the
+same Runtime Service generation, do not create a new task merely to evade a
+quarantined or interrupted task.
+
+## Runtime generation loss
+
+`SERVICE_LOST`, `GENERATION_MISMATCH`, `BROWSER_RUNTIME_UNAVAILABLE`, or an
+unknown task after a service reconnect means the Browser Runtime Service may
+have restarted. A new generation never restores the old evaluator, pages, or
+executable task state. Persisted receipts and resources are diagnostic records;
+they do not make the old task executable again.
+
+For an interrupted mutation:
+
+1. Preserve any receipt already returned by the old generation.
+2. Do not resubmit the mutation under either the old or a new request ID.
+3. After the new generation is ready, create a task only for read-only
+   inspection of externally visible application state.
+4. Retry the mutation only when that inspection proves it did not occur.
+
+Do not start, stop, or restart the Runtime Service. Browser owns its process and
+restart policy.
+
+## Idempotent request IDs
+
+Choose IDs that state intent and order:
+
+```text
+open-dashboard-01
+filter-breached-02
+submit-escalation-03
+verify-escalation-04
+```
+
+Calling `evaluate` again with `submit-escalation-03` retrieves the existing
+operation; it does not run new code. Never assign that ID to changed code.
+
+## Large resources
+
+Prefer returning a small aggregate. When the result is a resource handle:
+
+1. Run `tabbit-cli resource --task '<name>' --resource '<id>' --offset 0`.
+2. Append the returned slice.
+3. Continue with exactly the returned `nextOffset`.
+4. Stop when `eof` is true.
+
+Do not request a slice length; the server fixes each slice at at most 8192
+bytes. Avoid echoing the full resource into the final response when a compact
+answer is sufficient.
+
+## Cleanup
+
+Run `tabbit-cli finish --task '<name>'` exactly once after verification
+or when abandoning a failed task. A successful result is:
+
+```json
+{"taskId":"task-...","finished":true,"keep":false}
+```
+
+If `finish` fails because the Runtime Service generation disappeared, Browser
+has already revoked that generation and closes its Browser sessions. Report
+that task-level cleanup could not be confirmed; do not start a controller or a
+fallback browser.

package/update-check.js

@@ -0,0 +1,177 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const FETCH_TIMEOUT_MS = 1500
+const CHANGELOG_MAX_CHARS = 500
+// The raw CDN carries no GitHub API rate limit, which unauthenticated checks
+// from shared egress IPs would otherwise exhaust within the hour.
+const DEFAULT_CHANGELOG_URL = 'https://raw.githubusercontent.com/Tabbit-Browser/dsh-plugin/main/CHANGELOG.md'
+const PACKAGE_URL = new URL('./package.json', import.meta.url)
+
+let cachedLocalVersion
+
+function numericVersion(version) {
+  const match = String(version ?? '').trim().match(/^v?(\d+(?:\.\d+)*)/i)
+  return match ? match[1].split('.').map(Number) : undefined
+}
+
+export function compareVersions(left, right) {
+  const leftParts = numericVersion(left)
+  const rightParts = numericVersion(right)
+  if (!leftParts || !rightParts) return undefined
+  const length = Math.max(leftParts.length, rightParts.length)
+  for (let index = 0; index < length; index += 1) {
+    const a = leftParts[index] ?? 0
+    const b = rightParts[index] ?? 0
+    if (a !== b) return a > b ? 1 : -1
+  }
+  return 0
+}
+
+export function flattenChangelog(text) {
+  return String(text ?? '').replace(/\s+/g, ' ').trim()
+}
+
+export function truncateChangelog(text) {
+  const value = flattenChangelog(text)
+  if (value.length <= CHANGELOG_MAX_CHARS) return value
+  return `${value.slice(0, CHANGELOG_MAX_CHARS - 1).trimEnd()}…`
+}
+
+export function parseLatestChangelog(markdown) {
+  const match = String(markdown ?? '').match(/^## +(v?\d+(?:\.\d+)+).*$/m)
+  if (!match) throw new Error('Latest changelog has no version heading.')
+  const version = numericVersion(match[1])?.join('.')
+  if (!version) throw new Error('Latest changelog heading has no usable version.')
+  const sectionStart = match.index + match[0].length
+  const nextSection = String(markdown).slice(sectionStart).search(/^## +/m)
+  const section = nextSection === -1
+    ? String(markdown).slice(sectionStart)
+    : String(markdown).slice(sectionStart, sectionStart + nextSection)
+  return { version, changelog: truncateChangelog(section) }
+}
+
+export function defaultCacheFile(env = process.env, platform = process.platform) {
+  const base = env.XDG_CACHE_HOME
+    || (platform === 'win32'
+      ? env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
+      : undefined)
+    || join(homedir(), '.cache')
+  return join(base, 'tabbit-dsh', 'update-check.json')
+}
+
+export async function readLocalVersion() {
+  if (cachedLocalVersion !== undefined) return cachedLocalVersion ?? undefined
+  try {
+    const parsed = JSON.parse(await readFile(PACKAGE_URL, 'utf8'))
+    cachedLocalVersion = typeof parsed.version === 'string' ? parsed.version : null
+  } catch {
+    cachedLocalVersion = null
+  }
+  return cachedLocalVersion ?? undefined
+}
+
+export async function readCachedCheck(cacheFile) {
+  try {
+    const parsed = JSON.parse(await readFile(cacheFile, 'utf8'))
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+async function writeCachedCheck(cacheFile, state) {
+  await mkdir(dirname(cacheFile), { recursive: true })
+  await writeFile(cacheFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+}
+
+export async function fetchLatestChangelog({
+  url = process.env.TABBIT_PLUGIN_UPDATE_URL || DEFAULT_CHANGELOG_URL,
+  timeoutMs = FETCH_TIMEOUT_MS,
+  fetchImpl = fetch,
+} = {}) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetchImpl(url, { signal: controller.signal })
+    if (!response.ok) throw new Error(`Update check failed with HTTP ${response.status}.`)
+    return parseLatestChangelog(await response.text())
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function isRecent(timestamp, now) {
+  return typeof timestamp === 'number' && now - timestamp < DAY_MS
+}
+
+export function summarizeUpdate({
+  currentVersion,
+  latestVersion,
+  changelog,
+  dismissedVersion,
+}) {
+  if (!currentVersion || !latestVersion) return { status: 'unknown', currentVersion }
+  if (compareVersions(latestVersion, currentVersion) !== 1 || latestVersion === dismissedVersion) {
+    return { status: 'current', currentVersion, latestVersion }
+  }
+  return { status: 'update-available', currentVersion, latestVersion, changelog }
+}
+
+function summaryFromCache(currentVersion, cached) {
+  return summarizeUpdate({
+    currentVersion,
+    latestVersion: cached.latestVersion,
+    changelog: cached.changelog,
+    dismissedVersion: cached.dismissedVersion,
+  })
+}
+
+async function fetchAndCacheRelease({ currentVersion, cached, cacheFile, now, fetchRelease }) {
+  const state = { ...cached, lastAttemptAt: now }
+  try {
+    const release = await fetchRelease()
+    state.checkedAt = now
+    state.latestVersion = release.version
+    state.changelog = release.changelog
+  } catch {
+    // Keep lastAttemptAt so the failure stays silent for a day before retrying.
+  }
+  try {
+    await writeCachedCheck(cacheFile, state)
+  } catch {
+    // A read-only cache must not break the check itself.
+  }
+  return summaryFromCache(currentVersion, state)
+}
+
+export async function checkPluginUpdate({
+  now = Date.now(),
+  cacheFile = defaultCacheFile(),
+  fetchRelease = fetchLatestChangelog,
+  readVersion = readLocalVersion,
+  force = false,
+} = {}) {
+  const currentVersion = await readVersion()
+  const cached = await readCachedCheck(cacheFile)
+  if (!force) {
+    if (isRecent(cached.checkedAt, now) && cached.latestVersion) {
+      return summaryFromCache(currentVersion, cached)
+    }
+    if (isRecent(cached.lastAttemptAt, now)) {
+      return { status: 'unknown', currentVersion }
+    }
+  }
+  return fetchAndCacheRelease({ currentVersion, cached, cacheFile, now, fetchRelease })
+}
+
+export async function dismissUpdate(version, {
+  cacheFile = defaultCacheFile(),
+} = {}) {
+  const cached = await readCachedCheck(cacheFile)
+  const state = { ...cached, dismissedVersion: String(version ?? '').trim() }
+  await writeCachedCheck(cacheFile, state)
+  return state
+}