agentic-qe 3.9.7 → 3.9.9

package/.claude/skills/qe-browser/scripts/lib/vibium.js

@@ -0,0 +1,330 @@
+// Shared helpers for qe-browser scripts.
+// Shells out to the `vibium` CLI and parses its --json output.
+//
+// Why shell-out instead of the vibium npm client:
+//   - Keeps this wrapper language-agnostic and truly thin
+//   - Matches how other AQE skills (a11y-ally, testability-scoring) invoke external tools
+//   - Lets us upgrade Vibium independently without touching our code
+
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+const SKILL_NAME = 'qe-browser';
+const SKILL_VERSION = '1.0.0';
+const TRUST_TIER = 3;
+
+// F1 (Phase 6): typed error so downstream skills can distinguish
+// "vibium isn't installed" from "vibium ran but the test failed".
+// The Fallback Policy in SKILL.md says scripts must surface this as a
+// status: "skipped" envelope with reason: "browser-engine-unavailable"
+// — see unavailableEnvelope() / runOrSkip() below.
+class VibiumUnavailableError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'VibiumUnavailableError';
+    // Stable contract field that downstream code can `instanceof`-check OR
+    // duck-type via this property when crossing module boundaries (e.g.
+    // when the helper is loaded from a different node_modules tree).
+    this.code = 'BROWSER_ENGINE_UNAVAILABLE';
+  }
+}
+
+// Inject `--headless` into every vibium call by default. The qe-browser
+// helper scripts are designed for QE / CI use cases where there's no
+// display server, and Vibium defaults to "visible by default" which fails
+// in headless containers with "Missing X server or $DISPLAY". Users who
+// want a visible browser for interactive debugging should call vibium
+// directly, not through these helpers.
+//
+// Opt out by setting QE_BROWSER_HEADED=1 in the environment.
+function injectHeadless(args) {
+  if (process.env.QE_BROWSER_HEADED === '1') return args;
+  if (args.includes('--headless') || args.includes('--headed')) return args;
+  return ['--headless', ...args];
+}
+
+function vibium(args, { input, timeoutMs = 30000 } = {}) {
+  const finalArgs = injectHeadless(args);
+  const result = spawnSync('vibium', finalArgs, {
+    encoding: 'utf8',
+    input,
+    timeout: timeoutMs,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+  // F1: throw a TYPED error so the per-script main() can catch instanceof
+  // VibiumUnavailableError and emit the documented "skipped" envelope
+  // instead of a generic "failed" with the reason buried in `actual`.
+  if (result.error && result.error.code === 'ENOENT') {
+    throw new VibiumUnavailableError(
+      'vibium binary not found on PATH. Install via `npm install -g vibium` or run `aqe init`.'
+    );
+  }
+
+  return {
+    status: result.status,
+    stdout: (result.stdout || '').toString(),
+    stderr: (result.stderr || '').toString(),
+  };
+}
+
+function vibiumJson(args, opts) {
+  const withJson = args.includes('--json') ? args : [...args, '--json'];
+  const res = vibium(withJson, opts);
+  if (res.status !== 0) {
+    const err = new Error(
+      `vibium ${args[0] || ''} exited ${res.status}: ${res.stderr.trim() || res.stdout.trim()}`
+    );
+    err.stdout = res.stdout;
+    err.stderr = res.stderr;
+    err.exitCode = res.status;
+    throw err;
+  }
+  const trimmed = res.stdout.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch (_err) {
+    // Some vibium commands emit non-JSON even with --json on error paths;
+    // return raw text so callers can decide what to do.
+    return { __raw: trimmed };
+  }
+}
+
+// Vibium's `eval` (with or without --stdin) returns the LAST EXPRESSION's
+// value, NOT console.log output. With --json the response shape is:
+//   { ok: true, result: "<stringified value>" }
+// where `result` is a STRING if the expression returned a string, or a
+// Go-side serialization if it returned a non-string object. So our scripts
+// MUST wrap their return value in JSON.stringify(...) and we parse the
+// `result` field as JSON ourselves to get a real JS object back.
+//
+// Verified on Vibium v26.3.18 (2026-04-09).
+function unwrapEvalResult(payload) {
+  if (payload === null || payload === undefined) return null;
+  // payload from vibiumJson is already a parsed object: { ok, result } or { __raw }
+  if (payload && typeof payload === 'object' && 'ok' in payload && 'result' in payload) {
+    if (payload.ok !== true) {
+      throw new Error(`vibium eval failed: ${JSON.stringify(payload)}`);
+    }
+    const result = payload.result;
+    if (typeof result === 'string') {
+      // The script wrapped its return value in JSON.stringify so parse it.
+      try {
+        return JSON.parse(result);
+      } catch (_e) {
+        return result;
+      }
+    }
+    return result;
+  }
+  return payload;
+}
+
+function vibiumEval(expression) {
+  const raw = vibiumJson(['eval', '--json', expression]);
+  return unwrapEvalResult(raw);
+}
+
+function vibiumEvalStdin(script) {
+  const raw = vibiumJson(['eval', '--stdin', '--json'], { input: script });
+  return unwrapEvalResult(raw);
+}
+
+function envelope({
+  operation,
+  summary,
+  status = 'success',
+  details = {},
+  metadata = {},
+  vibiumUnavailable = false,
+  reason = undefined,
+}) {
+  const env = {
+    skillName: SKILL_NAME,
+    version: SKILL_VERSION,
+    timestamp: new Date().toISOString(),
+    status,
+    trustTier: TRUST_TIER,
+    output: {
+      operation,
+      summary,
+      ...details,
+    },
+    metadata,
+  };
+  // Top-level flag so downstream skills can branch on the contract without
+  // walking output.* sub-fields. Only set when true to keep the happy-path
+  // envelope shape unchanged for the 99% case.
+  if (vibiumUnavailable) env.vibiumUnavailable = true;
+  if (reason !== undefined) env.output.reason = reason;
+  return env;
+}
+
+// F1: produce the documented "skipped" envelope when vibium is missing.
+// Contract per SKILL.md Fallback Policy:
+//   status:                 "skipped"
+//   output.reason:          "browser-engine-unavailable"
+//   vibiumUnavailable:      true (top-level)
+//   output.summary:         actionable install guidance
+function unavailableEnvelope(operation, message) {
+  return envelope({
+    operation,
+    summary: message,
+    status: 'skipped',
+    vibiumUnavailable: true,
+    reason: 'browser-engine-unavailable',
+    details: {
+      error: message,
+      remediation: [
+        'Install vibium globally: `npm install -g vibium`',
+        'Or re-run `aqe init` to install via the AQE bootstrap',
+        'Set QE_BROWSER_HEADED=1 only for interactive debugging (not the cause here)',
+      ],
+    },
+    metadata: { executionTimeMs: 0 },
+  });
+}
+
+// Predicate so per-script catch blocks can decide whether to swallow an
+// error (regular failure) or re-throw it so the outer runOrSkip can emit
+// the skipped envelope. Cross-module-safe via the duck-typed `code` field.
+function isVibiumUnavailable(err) {
+  return Boolean(
+    err &&
+      (err instanceof VibiumUnavailableError ||
+        err.code === 'BROWSER_ENGINE_UNAVAILABLE' ||
+        // The error string from vibium() also matches as a final fallback
+        // in case both the prototype and the code field were lost while
+        // crossing some serialization boundary.
+        (typeof err.message === 'string' &&
+          err.message.includes('vibium binary not found on PATH')))
+  );
+}
+
+// rethrowIfUnavailable: helper to use INSIDE per-script catch blocks so
+// that the documented missing-vibium contract bubbles past lower-level
+// "convert exception to failed envelope" handlers and reaches runOrSkip.
+//
+// Usage:
+//   try { ... vibium calls ... }
+//   catch (err) {
+//     rethrowIfUnavailable(err);
+//     return fail('myop', err.message);
+//   }
+function rethrowIfUnavailable(err) {
+  if (isVibiumUnavailable(err)) {
+    if (err instanceof VibiumUnavailableError) throw err;
+    // Promote a duck-typed error to a real VibiumUnavailableError so
+    // downstream code only has to handle one type.
+    throw new VibiumUnavailableError(err.message || 'browser engine unavailable');
+  }
+}
+
+// runOrSkip wraps a per-script main() so that any VibiumUnavailableError
+// thrown anywhere inside the operation is converted to the documented
+// skipped envelope. Each helper script's main() is `() => fn()` returning
+// the exit code from emit(). On unavailable, we emit() the skipped envelope
+// and return its exit code (2).
+function runOrSkip(operation, fn) {
+  try {
+    return fn();
+  } catch (err) {
+    if (isVibiumUnavailable(err)) {
+      return emit(unavailableEnvelope(operation, err.message));
+    }
+    throw err;
+  }
+}
+
+// parseArgs supports both `--key value` and `--key=value` forms.
+//
+// M5 (devil's-advocate finding): the previous implementation only handled
+// the space-separated form. A user typing `--threshold=0.5` got
+// `args['threshold=0.5'] = true` and a separate `args.threshold` was never
+// set, so the value silently defaulted. The equals form is the dominant
+// idiom in npm/node CLIs (`node --inspect=9229`), so we accept both. When
+// the next token is itself a flag (`--include-hidden --json`) we treat the
+// current flag as boolean — the same behavior as before.
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const stripped = token.slice(2);
+    // --key=value form: split on first '=' only so values containing '='
+    // (URLs, regex with capture group names, base64) survive intact.
+    const eqIdx = stripped.indexOf('=');
+    if (eqIdx !== -1) {
+      const key = stripped.slice(0, eqIdx);
+      const value = stripped.slice(eqIdx + 1);
+      args[key] = value;
+      continue;
+    }
+    const key = stripped;
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function readInlineOrFile(value) {
+  if (typeof value !== 'string') return value;
+  if (value.startsWith('@')) {
+    const fs = require('node:fs');
+    return fs.readFileSync(value.slice(1), 'utf8');
+  }
+  return value;
+}
+
+// Exit code contract (F1):
+//   0 — success: every assertion passed / operation completed cleanly
+//   1 — failed:  genuine assertion failure or operation error
+//   2 — skipped: vibium unavailable; environment problem, not a test result
+//
+// CI tooling can use this to distinguish "test legitimately failed" from
+// "we couldn't run the test because the browser engine isn't installed."
+function emit(env) {
+  process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
+  if (env.status === 'success') return 0;
+  if (env.status === 'skipped') return 2;
+  return 1;
+}
+
+function fail(operation, message, metadata = {}) {
+  return emit(
+    envelope({
+      operation,
+      summary: message,
+      status: 'failed',
+      details: { error: message },
+      metadata,
+    })
+  );
+}
+
+module.exports = {
+  SKILL_NAME,
+  SKILL_VERSION,
+  TRUST_TIER,
+  VibiumUnavailableError,
+  isVibiumUnavailable,
+  rethrowIfUnavailable,
+  vibium,
+  vibiumJson,
+  vibiumEval,
+  vibiumEvalStdin,
+  envelope,
+  unavailableEnvelope,
+  runOrSkip,
+  parseArgs,
+  readInlineOrFile,
+  emit,
+  fail,
+};

package/.claude/skills/qe-browser/scripts/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@aqe/qe-browser-scripts",
+  "version": "1.0.0",
+  "private": true,
+  "type": "commonjs",
+  "description": "Scoped package.json that keeps qe-browser helper scripts in CommonJS despite the repo root being ESM."
+}

package/.claude/skills/qe-browser/scripts/smoke-test.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# qe-browser smoke test
+#
+# Runs each helper script against pinned public fixtures (httpbin.org) and
+# verifies the output structure. This is the script that gates PR-reopen
+# per ADR-091 Phase 3 — it MUST be run on a machine with vibium installed
+# before the qe-browser PR is considered safe to reopen.
+#
+# Exit codes:
+#   0 — all smoke tests passed
+#   1 — at least one smoke test failed
+#   2 — vibium binary not on PATH (precondition unmet)
+#
+# Per feedback_no_unverified_failure_modes.md, this is the script we
+# actually run, not just write. Per feedback_synthetic_fixtures_dont_count,
+# all fixtures are pinned public endpoints (httpbin.org) — no synthetic
+# stubs, no inline HTML.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+PASS=0
+FAIL=0
+SKIPPED=0
+
+ok()   { echo -e "${GREEN}PASS${NC}  $1"; PASS=$((PASS + 1)); }
+bad()  { echo -e "${RED}FAIL${NC}  $1${2:+: $2}"; FAIL=$((FAIL + 1)); }
+skip() { echo -e "${YELLOW}SKIP${NC}  $1${2:+: $2}"; SKIPPED=$((SKIPPED + 1)); }
+
+# ---------------------------------------------------------------------------
+# Precondition: vibium on PATH
+# ---------------------------------------------------------------------------
+if ! command -v vibium >/dev/null 2>&1; then
+  echo -e "${RED}vibium binary not found on PATH${NC}"
+  echo "Install via: npm install -g vibium"
+  exit 2
+fi
+
+VIBIUM_VERSION=$(vibium --version 2>&1 | head -1)
+echo "Smoke testing against $VIBIUM_VERSION"
+echo "Skill dir: $SKILL_DIR"
+echo "Work dir:  $WORK_DIR"
+echo ""
+
+# ---------------------------------------------------------------------------
+# tc001 — assert.js url_contains against pinned httpbin form
+# ---------------------------------------------------------------------------
+vibium --headless go https://httpbin.org/forms/post >/dev/null 2>&1 || true
+RESULT=$(node "$SKILL_DIR/scripts/assert.js" --checks \
+  '[{"kind": "url_contains", "text": "httpbin.org/forms"}]' 2>&1)
+EXIT=$?
+if [ "$EXIT" = "0" ] && echo "$RESULT" | grep -q '"status": "success"'; then
+  ok "tc001 url_contains on httpbin form"
+else
+  bad "tc001 url_contains on httpbin form" "exit=$EXIT, result=$RESULT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc002 — assert.js selector_visible against pinned httpbin /html
+# ---------------------------------------------------------------------------
+vibium --headless go https://httpbin.org/html >/dev/null 2>&1 || true
+RESULT=$(node "$SKILL_DIR/scripts/assert.js" --checks \
+  '[{"kind": "selector_visible", "selector": "h1"}]' 2>&1)
+EXIT=$?
+if [ "$EXIT" = "0" ] && echo "$RESULT" | grep -q '"passed": true'; then
+  ok "tc002 selector_visible h1 on httpbin /html"
+else
+  bad "tc002 selector_visible h1 on httpbin /html" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc003 — assert.js failing assertion exits non-zero
+# ---------------------------------------------------------------------------
+RESULT=$(node "$SKILL_DIR/scripts/assert.js" --checks \
+  '[{"kind": "url_contains", "text": "this-does-not-exist"}]' 2>&1)
+EXIT=$?
+if [ "$EXIT" = "1" ] && echo "$RESULT" | grep -q '"status": "failed"'; then
+  ok "tc003 failing assertion exits 1"
+else
+  bad "tc003 failing assertion exits 1" "exit=$EXIT (expected 1)"
+fi
+
+# ---------------------------------------------------------------------------
+# tc004 — batch.js navigate + wait + assert in one call
+# ---------------------------------------------------------------------------
+RESULT=$(node "$SKILL_DIR/scripts/batch.js" --steps \
+  '[{"action":"go","url":"https://httpbin.org/html"},{"action":"wait_load"},{"action":"assert","checks":[{"kind":"url_contains","text":"/html"}]}]' \
+  --summary-only 2>&1)
+EXIT=$?
+if [ "$EXIT" = "0" ] && echo "$RESULT" | grep -q '"passedSteps": 3'; then
+  ok "tc004 batch 3-step happy path"
+else
+  bad "tc004 batch 3-step happy path" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc005 — batch.js stops on failure
+# ---------------------------------------------------------------------------
+RESULT=$(node "$SKILL_DIR/scripts/batch.js" --steps \
+  '[{"action":"go","url":"https://httpbin.org/html"},{"action":"click","selector":"#does-not-exist-selector"},{"action":"go","url":"https://httpbin.org/forms/post"}]' 2>&1)
+EXIT=$?
+if [ "$EXIT" = "1" ] && echo "$RESULT" | grep -q '"failedStep"'; then
+  ok "tc005 batch stops on first failure"
+else
+  bad "tc005 batch stops on first failure" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc006 — visual-diff.js creates baseline on first run
+#
+# Set explicit viewport BEFORE screenshot so the two visual-diff runs have
+# the same dimensions. Without this the chromium headless window picks
+# whatever size it likes per run, and httpbin.org/html renders at different
+# sizes between runs (768×654 vs 765×672 observed), making pixel-diff
+# spuriously fail. This is documented in references/assertion-kinds.md.
+# ---------------------------------------------------------------------------
+rm -rf "$PWD/.aqe/visual-baselines/smoke_test_baseline"*
+vibium --headless viewport 1280 720 >/dev/null 2>&1 || true
+vibium --headless go https://httpbin.org/html >/dev/null 2>&1 || true
+RESULT=$(node "$SKILL_DIR/scripts/visual-diff.js" --name smoke_test_baseline 2>&1)
+EXIT=$?
+if [ "$EXIT" = "0" ] && echo "$RESULT" | grep -q '"baseline_created"'; then
+  ok "tc006 visual-diff baseline created"
+else
+  bad "tc006 visual-diff baseline created" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc007 — visual-diff.js matches second identical run
+#
+# Force the same viewport before re-shooting so dimensions match the baseline.
+# ---------------------------------------------------------------------------
+vibium --headless viewport 1280 720 >/dev/null 2>&1 || true
+RESULT=$(node "$SKILL_DIR/scripts/visual-diff.js" --name smoke_test_baseline 2>&1)
+EXIT=$?
+if [ "$EXIT" = "0" ] && echo "$RESULT" | grep -qE '"(match|baseline_created)"'; then
+  ok "tc007 visual-diff second run matches"
+else
+  bad "tc007 visual-diff second run matches" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc008 — check-injection.js clean page
+# ---------------------------------------------------------------------------
+vibium --headless go https://httpbin.org/html >/dev/null 2>&1 || true
+RESULT=$(node "$SKILL_DIR/scripts/check-injection.js" --include-hidden 2>&1)
+EXIT=$?
+if [ "$EXIT" = "0" ] && echo "$RESULT" | grep -q '"severity": "none"'; then
+  ok "tc008 check-injection clean page"
+else
+  bad "tc008 check-injection clean page" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc010 — intent-score.js submit_form on pinned httpbin form
+# ---------------------------------------------------------------------------
+vibium --headless go https://httpbin.org/forms/post >/dev/null 2>&1 || true
+RESULT=$(node "$SKILL_DIR/scripts/intent-score.js" --intent submit_form 2>&1)
+EXIT=$?
+if [ "$EXIT" = "0" ] && echo "$RESULT" | grep -q '"intent": "submit_form"'; then
+  ok "tc010 intent-score submit_form on httpbin form"
+else
+  bad "tc010 intent-score submit_form on httpbin form" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# tc011 — F1 contract: vibium-missing → skipped envelope + exit code 2
+# ---------------------------------------------------------------------------
+# Build a fake bin dir that contains node (so the helper can run) but NOT
+# vibium. The helper must:
+#   1. Throw VibiumUnavailableError from lib/vibium.js
+#   2. Have it caught by runOrSkip wrapping main()
+#   3. Emit a status: "skipped" envelope with vibiumUnavailable: true
+#   4. Exit with code 2 (not 1)
+FAKE_BIN="$WORK_DIR/fake-bin"
+mkdir -p "$FAKE_BIN"
+ln -sf "$(command -v node)" "$FAKE_BIN/node"
+RESULT=$(env -i PATH="$FAKE_BIN" HOME="$HOME" TERM=dumb \
+  node "$SKILL_DIR/scripts/assert.js" --checks '[{"kind":"url_contains","text":"foo"}]' 2>&1)
+EXIT=$?
+if [ "$EXIT" = "2" ] \
+  && echo "$RESULT" | grep -q '"status": "skipped"' \
+  && echo "$RESULT" | grep -q '"vibiumUnavailable": true' \
+  && echo "$RESULT" | grep -q '"reason": "browser-engine-unavailable"'; then
+  ok "tc011 F1 missing-vibium emits skipped envelope + exit 2"
+else
+  bad "tc011 F1 missing-vibium emits skipped envelope + exit 2" "exit=$EXIT"
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "─────────────────────────────────"
+echo "PASS:    $PASS"
+echo "FAIL:    $FAIL"
+echo "SKIPPED: $SKIPPED"
+echo "─────────────────────────────────"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0

package/.claude/skills/qe-browser/scripts/validate-config.json

@@ -0,0 +1,46 @@
+{
+  "skillName": "qe-browser",
+  "skillVersion": "1.0.0",
+  "requiredTools": [
+    "node",
+    "jq"
+  ],
+  "optionalTools": [
+    "vibium",
+    "pixelmatch",
+    "pngjs"
+  ],
+  "schemaPath": "schemas/output.json",
+  "requiredFields": [
+    "skillName",
+    "version",
+    "timestamp",
+    "status",
+    "trustTier",
+    "output"
+  ],
+  "requiredNonEmptyFields": [
+    ".output.operation",
+    ".output.summary"
+  ],
+  "mustContainTerms": [],
+  "mustNotContainTerms": [],
+  "enumValidations": {
+    ".status": [
+      "success",
+      "partial",
+      "failed",
+      "skipped"
+    ],
+    ".trustTier": [3],
+    ".output.operation": [
+      "assert",
+      "batch",
+      "visual-diff",
+      "check-injection",
+      "intent-score",
+      "navigate",
+      "capture"
+    ]
+  }
+}