browser-automation-skill 0.71.0

package/scripts/lib/node/totp-core.mjs

@@ -0,0 +1,52 @@
+// scripts/lib/node/totp-core.mjs — pure-node RFC 6238 TOTP primitives.
+//
+// Extracted from totp.mjs (phase-5 part 4-ii) so playwright-driver.mjs can
+// import the same logic for auto-replay (phase-5 part 4-iii). totp.mjs
+// remains the CLI shim that reads stdin and calls totpAt().
+//
+// No external deps — uses node's built-in crypto module.
+
+import { createHmac } from 'node:crypto';
+
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+export function base32Decode(b32) {
+  const cleaned = b32.toUpperCase().replace(/=+$/g, '').replace(/\s+/g, '');
+  let bits = '';
+  for (const ch of cleaned) {
+    const i = BASE32_ALPHABET.indexOf(ch);
+    if (i < 0) throw new Error(`invalid base32 character: '${ch}'`);
+    bits += i.toString(2).padStart(5, '0');
+  }
+  const bytes = [];
+  for (let i = 0; i + 8 <= bits.length; i += 8) {
+    bytes.push(parseInt(bits.slice(i, i + 8), 2));
+  }
+  return Buffer.from(bytes);
+}
+
+// totpAt — produce a TOTP code for a given timestamp (seconds since epoch).
+// Defaults: 6 digits, 30s period, HMAC-SHA1 (per common TOTP issuer practice).
+export function totpAt(secretBase32, timestampSec, digits = 6, period = 30, alg = 'sha1') {
+  const counter = Math.floor(timestampSec / period);
+  const counterBuf = Buffer.alloc(8);
+  // Big-endian 64-bit counter. Math.floor + lossy 32-bit handling for the
+  // upper word — acceptable for any timestamp before year ~2106.
+  counterBuf.writeUInt32BE(Math.floor(counter / 0x100000000), 0);
+  counterBuf.writeUInt32BE(counter >>> 0, 4);
+  const key = base32Decode(secretBase32);
+  const hmac = createHmac(alg, key).update(counterBuf).digest();
+  const offset = hmac[hmac.length - 1] & 0x0f;
+  const truncated =
+    ((hmac[offset] & 0x7f) << 24) |
+    (hmac[offset + 1] << 16) |
+    (hmac[offset + 2] << 8) |
+    hmac[offset + 3];
+  const code = truncated % Math.pow(10, digits);
+  return String(code).padStart(digits, '0');
+}
+
+// totpNow — convenience wrapper using Date.now().
+export function totpNow(secretBase32, digits = 6, period = 30, alg = 'sha1') {
+  return totpAt(secretBase32, Math.floor(Date.now() / 1000), digits, period, alg);
+}

package/scripts/lib/node/totp.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// scripts/lib/node/totp.mjs — CLI shim around scripts/lib/node/totp-core.mjs.
+//
+// Reads base32-encoded shared secret from stdin (typical TOTP issuer output:
+// "JBSWY3DPEHPK3PXP" etc.), produces the 6-digit code for the current 30s
+// window. Core logic lives in totp-core.mjs so playwright-driver.mjs can
+// import the same primitives for auto-replay (phase-5 part 4-iii).
+//
+// CLI:
+//   echo -n 'BASE32SECRET' | node totp.mjs
+//   → 6-digit code on stdout
+//
+// Optional env vars:
+//   TOTP_TIME_T (integer seconds since epoch) — override "now" for tests.
+//                Lets bats verify against RFC 6238 §A test vectors.
+//   TOTP_DIGITS (default 6) — code length.
+//   TOTP_PERIOD (default 30) — time-step in seconds.
+//   TOTP_ALG    (default SHA1) — HMAC algorithm. Most providers use SHA1.
+
+import { totpAt } from './totp-core.mjs';
+
+async function readAllStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+const secret = (await readAllStdin()).trim();
+if (!secret) {
+  process.stderr.write('totp: empty secret on stdin\n');
+  process.exit(2);
+}
+
+const t = process.env.TOTP_TIME_T
+  ? parseInt(process.env.TOTP_TIME_T, 10)
+  : Math.floor(Date.now() / 1000);
+const digits = parseInt(process.env.TOTP_DIGITS || '6', 10);
+const period = parseInt(process.env.TOTP_PERIOD || '30', 10);
+const alg = (process.env.TOTP_ALG || 'sha1').toLowerCase();
+
+try {
+  const code = totpAt(secret, t, digits, period, alg);
+  process.stdout.write(code + '\n');
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(`totp: ${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+}

package/scripts/lib/node/url-pattern-cluster.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// scripts/lib/node/url-pattern-cluster.mjs
+//
+// Phase 11 part 2-ii. Cluster URLs by templated pathname.
+//
+// Stdin:  {"urls": ["https://...", ...]}
+// Stdout: {"clusters": [{"templated": "/devices/:id", "urls": [...], "count": N}, ...]}
+//
+// Heuristic:
+//   numeric segment   (^[0-9]+$)                                       → :id
+//   UUID segment      (8-4-4-4-12 hex)                                 → :uuid
+//   slug segment      (^[a-z0-9_]+(-[a-z0-9_]+)+$/i + length ≥ 5)      → :slug
+//   other segments    → verbatim
+//
+// Slug heuristic (Pick A2) — locked decision:
+//   - Requires at least ONE hyphen separating alphanumeric groups.
+//   - Each side of every hyphen must be ≥1 char of [a-zA-Z0-9_].
+//   - Total segment length ≥ 5 chars (filters short codes like `a-b` or
+//     `1-2` which are more likely to be opaque identifiers than slugs).
+//   - All-numeric is already caught by the numeric branch above (which
+//     fires before slug detection in this `if`-chain order).
+//
+// Cross-site clustering not in scope (caller passes per-site URLs).
+
+let stdin = "";
+process.stdin.setEncoding("utf8");
+for await (const chunk of process.stdin) stdin += chunk;
+
+let payload;
+try {
+  payload = JSON.parse(stdin || "{}");
+} catch {
+  process.stdout.write(JSON.stringify({ clusters: [] }));
+  process.exit(0);
+}
+
+const urls = Array.isArray(payload.urls) ? payload.urls : [];
+
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const NUMERIC_RE = /^[0-9]+$/;
+const SLUG_RE = /^[a-z0-9_]+(-[a-z0-9_]+)+$/i;
+const MIN_SLUG_LEN = 5;
+
+function templatePathname(pathname) {
+  // Split preserves the leading "/" as an empty first element.
+  const parts = pathname.split("/");
+  const templated = parts.map((seg) => {
+    if (seg === "") return seg;
+    if (UUID_RE.test(seg)) return ":uuid";
+    if (NUMERIC_RE.test(seg)) return ":id";
+    // Pick A2: slug heuristic. Fires after numeric/UUID; only on hyphenated
+    // multi-group segments of length >= MIN_SLUG_LEN.
+    if (seg.length >= MIN_SLUG_LEN && SLUG_RE.test(seg)) return ":slug";
+    return seg;
+  });
+  return templated.join("/");
+}
+
+const buckets = new Map();
+for (const url of urls) {
+  if (typeof url !== "string") continue;
+  let pathname;
+  try {
+    pathname = new URL(url, "https://placeholder.local").pathname;
+  } catch {
+    continue;
+  }
+  const templated = templatePathname(pathname);
+  // Skip URLs whose templated form is identical to the original (no
+  // numeric/UUID segment matched) AND that haven't been seen before. This
+  // is what filters slug-shaped segments out of cluster proposals.
+  // (Identical templates DO still get bucketed if they collide; only the
+  // single-occurrence non-template URLs get suppressed below by the
+  // threshold filter.)
+  const bucket = buckets.get(templated) || [];
+  bucket.push(url);
+  buckets.set(templated, bucket);
+}
+
+// Only emit clusters where the templated form differs from at least one
+// constituent URL's pathname — otherwise it's just N copies of the same
+// literal URL, which isn't a "pattern".
+const clusters = [];
+for (const [templated, urlList] of buckets) {
+  let hasTemplating = false;
+  for (const url of urlList) {
+    let pathname;
+    try {
+      pathname = new URL(url, "https://placeholder.local").pathname;
+    } catch {
+      continue;
+    }
+    if (pathname !== templated) {
+      hasTemplating = true;
+      break;
+    }
+  }
+  if (!hasTemplating) continue;
+  clusters.push({ templated, urls: urlList, count: urlList.length });
+}
+
+process.stdout.write(JSON.stringify({ clusters }));

package/scripts/lib/node/url-pattern-resolver.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// scripts/lib/node/url-pattern-resolver.mjs
+//
+// Phase 11 part 1-i. URL → archetype resolution.
+//
+// Stdin:  {"patterns":[{"url_pattern":"/devices/:id","archetype_id":"…"}], "url":"https://…"}
+// Stdout: {"matched_pattern":"/devices/:id","archetype_id":"devices-detail"}  on hit
+//         null                                                                 on miss
+//
+// First-match-wins (callers reorder patterns to express priority).
+// Pattern is a pathname pattern; matched against the URL's pathname (URL
+// parsed with a placeholder origin so relative URLs work).
+//
+// Matcher subset (deliberate; v1):
+//   :name   → matches one path segment (non-slash chars)
+//   *       → matches any chars including slashes
+//   literal → matched verbatim
+//
+// Why not the URLPattern web standard? Because the global `URLPattern` is
+// only stable in Node 23.8+; GitHub Actions runners still default to Node
+// 20 (see https://github.blog/changelog/2025-09-19-...). A hand-rolled
+// matcher keeps behavior deterministic across all supported Node versions
+// and removes the npm-polyfill cost. URLPattern can replace this when the
+// CI baseline lifts to Node 24+ (target: mid-2026).
+
+let stdin = "";
+process.stdin.setEncoding("utf8");
+for await (const chunk of process.stdin) stdin += chunk;
+
+let payload;
+try {
+  payload = JSON.parse(stdin || "{}");
+} catch {
+  process.stdout.write("null");
+  process.exit(0);
+}
+
+const patterns = Array.isArray(payload.patterns) ? payload.patterns : [];
+const url = typeof payload.url === "string" ? payload.url : "";
+
+let pathname;
+try {
+  pathname = new URL(url, "https://placeholder.local").pathname;
+} catch {
+  process.stdout.write("null");
+  process.exit(0);
+}
+
+// Compile pattern → RegExp. :name matches one segment; * matches anything.
+function compile(pattern) {
+  // Escape regex metachars EXCEPT the two we re-introduce (`:` and `*`).
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  // :name → [^/]+ (one segment)
+  const withNamed = escaped.replace(/:[A-Za-z_][\w$]*/g, "[^/]+");
+  // * → .* (anything, slashes included)
+  const withStar = withNamed.replace(/\*/g, ".*");
+  return new RegExp("^" + withStar + "/?$");
+}
+
+for (const p of patterns) {
+  if (typeof p?.url_pattern !== "string") continue;
+  let re;
+  try {
+    re = compile(p.url_pattern);
+  } catch {
+    continue;
+  }
+  if (re.test(pathname)) {
+    process.stdout.write(JSON.stringify({
+      matched_pattern: p.url_pattern,
+      archetype_id: p.archetype_id,
+    }));
+    process.exit(0);
+  }
+}
+
+process.stdout.write("null");

package/scripts/lib/output.sh

@@ -0,0 +1,79 @@
+# scripts/lib/output.sh
+# Token-efficient adapter output helpers. Implements the contract from
+# docs/superpowers/specs/2026-05-01-token-efficient-adapter-output-design.md §3.
+#
+# Verbs and adapters MUST emit through these helpers — never hand-roll JSON.
+# Lint tier 3 (tests/lint.sh, Phase 3 Task 13) enforces it.
+
+[ -n "${BROWSER_SKILL_OUTPUT_LOADED:-}" ] && return 0
+readonly BROWSER_SKILL_OUTPUT_LOADED=1
+
+# Canonical status values (spec §3.1). Reject anything else at the helper boundary
+# so output stays parseable by jq routing logic.
+readonly _OUTPUT_STATUSES_OK="ok partial empty error aborted"
+
+# emit_summary key=value [key=value ...]
+# Required keys: verb, tool, why, status. duration_ms auto-fills from
+# SUMMARY_T0 (set by caller via `SUMMARY_T0=$(now_ms)` at verb entry).
+# Wraps summary_json from common.sh; adds key-presence + status-enum guards.
+emit_summary() {
+  local has_verb=0 has_tool=0 has_why=0 has_status=0 has_duration=0
+  local arg value
+  for arg in "$@"; do
+    case "${arg}" in
+      verb=*)         has_verb=1 ;;
+      tool=*)         has_tool=1 ;;
+      why=*)          has_why=1 ;;
+      status=*)
+        has_status=1
+        value="${arg#status=}"
+        if ! [[ " ${_OUTPUT_STATUSES_OK} " == *" ${value} "* ]]; then
+          die "${EXIT_USAGE_ERROR}" "emit_summary: status='${value}' not in {${_OUTPUT_STATUSES_OK// /, }}"
+        fi
+        ;;
+      duration_ms=*)  has_duration=1 ;;
+    esac
+  done
+
+  [ "${has_verb}" = "1" ]   || die "${EXIT_USAGE_ERROR}" "emit_summary: missing required key 'verb'"
+  [ "${has_tool}" = "1" ]   || die "${EXIT_USAGE_ERROR}" "emit_summary: missing required key 'tool'"
+  [ "${has_why}" = "1" ]    || die "${EXIT_USAGE_ERROR}" "emit_summary: missing required key 'why'"
+  [ "${has_status}" = "1" ] || die "${EXIT_USAGE_ERROR}" "emit_summary: missing required key 'status'"
+
+  if [ "${has_duration}" = "0" ] && [ -n "${SUMMARY_T0:-}" ]; then
+    local now elapsed
+    now="$(now_ms)"
+    elapsed=$((now - SUMMARY_T0))
+    summary_json "$@" "duration_ms=${elapsed}"
+    return
+  fi
+
+  summary_json "$@"
+}
+
+# emit_event EVENT_NAME [key=value ...]
+# Streaming JSON line with `.event = EVENT_NAME`. Spec §3.3.
+emit_event() {
+  local event="${1:-}"
+  shift || true
+  [ -n "${event}" ] || die "${EXIT_USAGE_ERROR}" "emit_event: empty event name"
+  summary_json "event=${event}" "$@"
+}
+
+# capture_path CATEGORY SITE EXT
+# Returns ${CAPTURES_DIR}/<category>/<site>--<ts>.<ext> and mkdir -p's the parent.
+# CATEGORY: snapshots | screenshots | hars | traces | videos | pdfs (spec §6).
+# SITE: must pass assert_safe_name (no traversal).
+# EXT: file extension without dot (e.g. png, har, yaml, webm, pdf, zip).
+capture_path() {
+  local category="$1" site="$2" ext="$3"
+  assert_safe_name "${category}" "capture-category"
+  assert_safe_name "${site}"     "site-name"
+  assert_safe_name "${ext}"      "capture-extension"
+
+  local ts
+  ts="$(date -u +%Y-%m-%dT%H%M%SZ)"
+  local dir="${CAPTURES_DIR:?CAPTURES_DIR not set; call init_paths first}/${category}"
+  mkdir -p "${dir}"
+  printf '%s/%s--%s.%s\n' "${dir}" "${site}" "${ts}" "${ext}"
+}