@guanlin4924/devflow-pi 0.1.96 → 0.1.98

package/plugins/devflow-quality/runtime/playwright/explore-host.mjs

@@ -0,0 +1,1015 @@
+// plugins/devflow-quality/runtime/playwright/src/explore/host.ts
+import readline from "node:readline";
+import fs2 from "node:fs";
+import path2 from "node:path";
+import process from "node:process";
+import { chromium } from "@playwright/test";
+
+// plugins/devflow-quality/runtime/playwright/src/network.ts
+var SUBRESOURCE_POLICIES = new Set(["same-site-plus-declared", "declared-only"]);
+var IMPLICIT_SCHEMES = new Set(["data:", "blob:", "about:"]);
+
+class ProfileError extends Error {
+  code = "environment_profile_invalid";
+}
+function normalizeOrigin(value, field) {
+  let u;
+  try {
+    u = new URL(value);
+  } catch {
+    throw new ProfileError(`${field}: not an absolute URL: ${value}`);
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:")
+    throw new ProfileError(`${field}: only http(s) origins allowed: ${value}`);
+  return u.origin;
+}
+function buildPolicy(profile) {
+  if (!profile || typeof profile !== "object")
+    throw new ProfileError("profile must be a JSON object");
+  if (typeof profile.base_url !== "string")
+    throw new ProfileError("base_url is required");
+  const listOf = (value, field) => {
+    if (value === undefined)
+      return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string"))
+      throw new ProfileError(`${field} must be an array of strings`);
+    return value;
+  };
+  const navigation = new Set(listOf(profile.navigation_origins, "navigation_origins").map((o) => normalizeOrigin(o, "navigation_origins")));
+  const api = new Set(listOf(profile.api_origins, "api_origins").map((o) => normalizeOrigin(o, "api_origins")));
+  if (navigation.size === 0)
+    throw new ProfileError("navigation_origins must not be empty");
+  const policy = profile.subresources?.policy ?? "same-site-plus-declared";
+  if (!SUBRESOURCE_POLICIES.has(policy))
+    throw new ProfileError(`unknown subresources.policy ${policy}`);
+  const subresourceOrigins = new Set(listOf(profile.subresources?.allowed_origins, "subresources.allowed_origins").map((o) => normalizeOrigin(o, "subresources.allowed_origins")));
+  const baseUrl = new URL(profile.base_url).toString();
+  if (!navigation.has(new URL(baseUrl).origin))
+    throw new ProfileError("base_url origin must be listed in navigation_origins");
+  const apiBaseUrl = profile.api_base_url ? new URL(profile.api_base_url).toString() : baseUrl;
+  return { baseUrl, apiBaseUrl, navigation, api, subresourcePolicy: policy, subresourceOrigins };
+}
+function sameSite(a, b) {
+  if (a.protocol !== b.protocol)
+    return false;
+  const ha = a.hostname;
+  const hb = b.hostname;
+  return ha === hb || ha.endsWith(`.${hb}`) || hb.endsWith(`.${ha}`);
+}
+function isAllowed(policy, rawUrl, kind) {
+  let u;
+  try {
+    u = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+  if (IMPLICIT_SCHEMES.has(u.protocol))
+    return kind === "subresource";
+  if (kind === "navigation")
+    return policy.navigation.has(u.origin);
+  if (kind === "api")
+    return policy.api.has(u.origin);
+  if (policy.navigation.has(u.origin) || policy.api.has(u.origin) || policy.subresourceOrigins.has(u.origin))
+    return true;
+  if (policy.subresourcePolicy === "same-site-plus-declared") {
+    for (const origin of policy.navigation)
+      if (sameSite(u, new URL(origin)))
+        return true;
+  }
+  return false;
+}
+function isTopLevelNavigation(request) {
+  try {
+    return request.isNavigationRequest() && request.frame().parentFrame() === null;
+  } catch {
+    return false;
+  }
+}
+
+class NetworkRecorder {
+  redactor;
+  entries = [];
+  violations = [];
+  starts = new WeakMap;
+  constructor(redactor) {
+    this.redactor = redactor;
+  }
+  api(entry) {
+    this.entries.push({ source: "api", ...entry, url: this.redactor.url(entry.url) });
+  }
+  violation(url, kind) {
+    this.violations.push({ url: this.redactor.url(url), kind, at: Date.now() });
+  }
+  async install(context, policy) {
+    await context.route("**/*", async (route) => {
+      const request = route.request();
+      const topLevel = isTopLevelNavigation(request);
+      const kind = topLevel ? "navigation" : "subresource";
+      if (isAllowed(policy, request.url(), kind)) {
+        await route.continue();
+        return;
+      }
+      this.violation(request.url(), kind);
+      this.entries.push({
+        source: "page",
+        method: request.method(),
+        url: this.redactor.url(request.url()),
+        status: null,
+        duration_ms: null,
+        blocked: true,
+        resource_type: request.resourceType()
+      });
+      await route.abort("blockedbyclient");
+    });
+    context.on("request", (request) => {
+      this.starts.set(request, Date.now());
+      if (request.redirectedFrom()) {
+        const topLevel = isTopLevelNavigation(request);
+        const kind = topLevel ? "navigation" : "subresource";
+        if (!isAllowed(policy, request.url(), kind))
+          this.violation(request.url(), topLevel ? "navigation" : kind);
+      }
+    });
+    const finish = async (request, failure) => {
+      const started = this.starts.get(request);
+      if (failure === "net::ERR_BLOCKED_BY_CLIENT")
+        return;
+      let status = null;
+      try {
+        status = (await request.response())?.status() ?? null;
+      } catch {
+        status = null;
+      }
+      this.entries.push({
+        source: "page",
+        method: request.method(),
+        url: this.redactor.url(request.url()),
+        status,
+        duration_ms: started ? Date.now() - started : null,
+        blocked: false,
+        resource_type: request.resourceType(),
+        ...failure ? { failure: this.redactor.text(failure) } : {}
+      });
+    };
+    context.on("requestfinished", (request) => void finish(request));
+    context.on("requestfailed", (request) => void finish(request, request.failure()?.errorText ?? "failed"));
+  }
+}
+
+// plugins/devflow-quality/runtime/playwright/src/redact.ts
+var REDACTED = "***";
+var SENSITIVE_KEY = /(pass(word|wd)?|secret|token|auth|session|cookie|api[-_]?key|signature|sig|credential|private)/i;
+var MAX_ERROR_LENGTH = 2000;
+var ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
+
+class Redactor {
+  values = [];
+  add(value) {
+    if (value === undefined || value === null)
+      return;
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    if (!text)
+      return;
+    if (!this.values.includes(text)) {
+      this.values.push(text);
+      this.values.sort((a, b) => b.length - a.length);
+    }
+    for (const encoded of [encodeURIComponent(text), new URLSearchParams({ v: text }).toString().slice(2)]) {
+      if (encoded !== text && !this.values.includes(encoded))
+        this.values.push(encoded);
+    }
+    this.values.sort((a, b) => b.length - a.length);
+  }
+  list() {
+    return [...this.values];
+  }
+  text(input) {
+    let out = input;
+    for (const v of this.values)
+      out = out.split(v).join(REDACTED);
+    return out;
+  }
+  url(input) {
+    let masked = input;
+    try {
+      const u = new URL(input);
+      if (u.username || u.password) {
+        u.username = u.username ? REDACTED : "";
+        u.password = u.password ? REDACTED : "";
+      }
+      for (const key of [...u.searchParams.keys()]) {
+        if (SENSITIVE_KEY.test(key))
+          u.searchParams.set(key, REDACTED);
+      }
+      masked = u.toString();
+    } catch {}
+    return this.text(masked);
+  }
+  value(input) {
+    if (typeof input === "string")
+      return this.text(input);
+    if (Array.isArray(input))
+      return input.map((v) => this.value(v));
+    if (input && typeof input === "object") {
+      return Object.fromEntries(Object.entries(input).map(([k, v]) => [k, SENSITIVE_KEY.test(k) ? REDACTED : this.value(v)]));
+    }
+    if (input !== undefined && input !== null && this.values.includes(String(input)))
+      return REDACTED;
+    return input;
+  }
+  error(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const text = this.text(raw.replace(ANSI, ""));
+    return text.length > MAX_ERROR_LENGTH ? `${text.slice(0, MAX_ERROR_LENGTH)}…` : text;
+  }
+}
+
+// plugins/devflow-quality/runtime/playwright/src/explore/view.ts
+var INTERACTIVE = new Set(["button", "link", "textbox", "searchbox", "checkbox", "radio", "combobox", "listbox", "option", "menuitem", "menuitemcheckbox", "menuitemradio", "tab", "switch", "slider", "spinbutton", "treeitem"]);
+var NAMEABLE = new Set(["dialog", "alertdialog", "region", "form", "navigation", ...INTERACTIVE]);
+var INFO = new Set(["heading", "alert", "status", "dialog", "alertdialog"]);
+var CONTEXT = new Set(["dialog", "alertdialog", "form", "navigation", "banner", "main", "region", "table", "row", "tabpanel", "menu"]);
+var TEXT_CONTAINERS = new Set(["dialog", "alertdialog", "alert", "status"]);
+var LINE = /^(\s*)- (.*)$/;
+function colonOutsideQuotes(s) {
+  let quoted = false;
+  for (let i = 0;i < s.length; i++) {
+    if (s[i] === "\\") {
+      i++;
+      continue;
+    }
+    if (s[i] === '"')
+      quoted = !quoted;
+    else if (s[i] === ":" && !quoted && (i + 1 === s.length || s[i + 1] === " "))
+      return i;
+  }
+  return -1;
+}
+function parseSnapshot(yaml) {
+  const nodes = [];
+  const stack = [];
+  for (const raw of yaml.split(`
+`)) {
+    const match = LINE.exec(raw);
+    if (!match)
+      continue;
+    const indent = match[1].length;
+    while (stack.length && stack[stack.length - 1].indent >= indent)
+      stack.pop();
+    const parent = stack.length ? stack[stack.length - 1].node : null;
+    let body = match[2];
+    if (body.startsWith("/"))
+      continue;
+    const node = { role: "", name: "", attrs: {}, value: "", ref: "", parent, ctx: "" };
+    if (body.startsWith("text:")) {
+      node.role = "text";
+      node.value = body.slice(5).trim();
+    } else {
+      const colon = colonOutsideQuotes(body);
+      if (colon >= 0) {
+        node.value = body.slice(colon + 1).trim().replace(/^"|"$/g, "");
+        body = body.slice(0, colon);
+      }
+      node.role = body.split(/[\s[]/, 1)[0];
+      const name = body.match(/^\S+ "((?:[^"\\]|\\.)*)"/);
+      if (name)
+        node.name = name[1].replace(/\\"/g, '"');
+      for (const [, key, value] of body.matchAll(/\[([\w-]+)(?:=([^\]]*))?\]/g))
+        node.attrs[key] = value ?? true;
+      node.ref = typeof node.attrs.ref === "string" ? node.attrs.ref : "";
+      delete node.attrs.ref;
+      delete node.attrs.cursor;
+      delete node.attrs.active;
+    }
+    nodes.push(node);
+    stack.push({ indent, node });
+  }
+  return nodes;
+}
+function ancestors(node) {
+  const out = [];
+  for (let p = node.parent;p; p = p.parent)
+    out.push(p);
+  return out;
+}
+function prune(nodes, redactor, passwordRefs = new Set) {
+  const view = new Map;
+  let textSeq = 0;
+  const mask = (value) => redactor ? redactor.text(value) : value;
+  for (const node of nodes) {
+    const anc = ancestors(node);
+    const inText = anc.some((a) => TEXT_CONTAINERS.has(a.role));
+    if (!(INTERACTIVE.has(node.role) || INFO.has(node.role) || inText && (node.role === "text" || node.role === "paragraph") && node.value))
+      continue;
+    const ctx = anc.filter((a) => CONTEXT.has(a.role)).reverse().map((a) => a.name ? `${a.role} "${mask(a.name)}"` : a.role).join(" > ");
+    const copy = { ...node, attrs: { ...node.attrs }, name: mask(node.name), value: mask(node.value), ctx };
+    if (passwordRefs.has(node.ref))
+      copy.value = REDACTED;
+    if (redactor)
+      copy.value = redactor.text(copy.value);
+    view.set(node.ref || `text#${anc[0]?.ref ?? "root"}#${textSeq++}`, copy);
+  }
+  return view;
+}
+function format(node, redactor) {
+  const mask = (value) => redactor?.text(value) ?? value;
+  const attrs = Object.entries(node.attrs).map(([key, value]) => value === true ? `[${key}]` : `[${key}=${mask(value)}]`).join(" ");
+  const parts = [node.role];
+  if (node.name)
+    parts.push(`"${mask(node.name)}"`);
+  if (attrs)
+    parts.push(attrs);
+  if (node.ref)
+    parts.push(`[ref=${node.ref}]`);
+  let result = parts.join(" ");
+  if (node.value)
+    result += `: ${mask(node.value)}`;
+  if (node.ctx)
+    result += `  (in ${mask(node.ctx)})`;
+  return result;
+}
+var signature = (node) => JSON.stringify([node.role, node.name, node.attrs, node.value, node.ctx]);
+function diffViews(previous, next, redactor) {
+  const lines = [];
+  const added = [];
+  for (const [key, node] of next) {
+    const old = previous.get(key);
+    if (!old)
+      added.push(node);
+    else if (signature(old) !== signature(node))
+      lines.push(`~ ${format(old, redactor)}
+  → ${format(node, redactor)}`);
+  }
+  const removed = [...previous].filter(([key]) => !next.has(key)).map(([, node]) => node);
+  for (const node of added) {
+    const i = removed.findIndex((old) => old.role === node.role && old.ctx === node.ctx && old.role !== "text");
+    if (i >= 0)
+      lines.push(`~ ${format(removed.splice(i, 1)[0], redactor)}
+  → ${format(node, redactor)}`);
+    else
+      lines.push(`+ ${format(node, redactor)}`);
+  }
+  for (const node of removed)
+    lines.push(`- ${format(node, redactor)}`);
+  return lines;
+}
+async function passwordRefs(page, nodes) {
+  const out = new Set;
+  for (const node of nodes)
+    if (node.ref && (node.role === "textbox" || node.role === "searchbox")) {
+      const locator = page.locator(`aria-ref=${node.ref}`);
+      if (await locator.count() === 1 && (await locator.getAttribute("type"))?.toLowerCase() === "password")
+        out.add(node.ref);
+    }
+  return out;
+}
+async function nameRows(page, nodes) {
+  for (const node of nodes.filter((item) => item.role === "row" && item.ref)) {
+    const row = page.locator(`aria-ref=${node.ref}`);
+    if (await row.count() !== 1)
+      continue;
+    const cells = row.locator(":scope > td:visible, :scope > th:visible");
+    for (let i = 0;i < await cells.count(); i++) {
+      const text = (await cells.nth(i).innerText()).replace(/\s+/g, " ").trim();
+      if (text) {
+        node.name = text.slice(0, 40);
+        break;
+      }
+    }
+  }
+  for (const node of nodes.filter((item) => item.ref)) {
+    const rowNode = [node, ...ancestors(node)].find((item) => item.role === "row");
+    if (!rowNode || rowNode.name)
+      continue;
+    const row = page.locator(`aria-ref=${node.ref}`).locator("xpath=ancestor::tr[1]");
+    if (await row.count() !== 1)
+      continue;
+    const cells = row.locator(":scope > td:visible, :scope > th:visible");
+    for (let i = 0;i < await cells.count(); i++) {
+      const text = (await cells.nth(i).innerText()).replace(/\s+/g, " ").trim();
+      if (text) {
+        rowNode.name = text.slice(0, 40);
+        break;
+      }
+    }
+  }
+}
+async function nameContainers(page, nodes) {
+  for (const node of nodes.filter((item) => item.ref && !item.name && NAMEABLE.has(item.role))) {
+    const element = page.locator(`aria-ref=${node.ref}`);
+    if (await element.count() !== 1)
+      continue;
+    const name = await element.evaluate((item) => {
+      const ariaLabel = item.getAttribute("aria-label")?.trim();
+      if (ariaLabel)
+        return ariaLabel.replace(/\s+/g, " ").trim();
+      const ids = item.getAttribute("aria-labelledby")?.trim().split(/\s+/).filter(Boolean) ?? [];
+      return ids.map((id) => document.getElementById(id)?.textContent ?? "").join(" ").replace(/\s+/g, " ").trim();
+    });
+    if (!name)
+      continue;
+    const roleLocator = page.getByRole(node.role, { name, exact: true });
+    if (await sameUniqueElement(roleLocator, element))
+      node.name = name;
+  }
+}
+async function sameUniqueElement(candidate, element) {
+  if (await candidate.count() !== 1)
+    return false;
+  const candidateHandle = await candidate.elementHandle();
+  if (!candidateHandle)
+    return false;
+  try {
+    return await element.evaluate((node, other) => node === other, candidateHandle);
+  } finally {
+    await candidateHandle.dispose();
+  }
+}
+
+class ExplorerView {
+  page;
+  redactor;
+  previous = null;
+  previousUrl = null;
+  last = null;
+  constructor(page, redactor) {
+    this.page = page;
+    this.redactor = redactor;
+  }
+  hasRef(ref) {
+    return Boolean(this.last?.has(ref));
+  }
+  node(ref) {
+    return this.last?.get(ref);
+  }
+  async observe(options = {}, settled = true) {
+    let scope = this.page.locator("body");
+    if (options.scope) {
+      const rawScope = options.scope;
+      const ref = /^(?:aria-ref=)?(e\d+)$/.exec(rawScope);
+      if (ref) {
+        if (!this.hasRef(ref[1]))
+          throw Object.assign(new Error(`unknown or stale ref ${ref[1]}`), { code: "stale_ref" });
+        scope = this.page.locator(`aria-ref=${ref[1]}`);
+      } else if (rawScope.startsWith("role=")) {
+        const value = rawScope.slice(5);
+        const [role, ...nameParts] = value.split(":");
+        if (!/^[-a-z]+$/.test(role) || nameParts.length && !nameParts.join(":").length)
+          throw Object.assign(new Error("scope must be eN, aria-ref=eN, role=<role>[:<name>], or testid=<id>"), { code: "invalid_params" });
+        scope = nameParts.length ? this.page.getByRole(role, { name: nameParts.join(":"), exact: true }) : this.page.getByRole(role);
+      } else if (rawScope.startsWith("testid=") && rawScope.slice(7))
+        scope = this.page.getByTestId(rawScope.slice(7));
+      else
+        throw Object.assign(new Error("scope must be eN, aria-ref=eN, role=<role>[:<name>], or testid=<id>"), { code: "invalid_params" });
+      const scopeCount = await scope.count();
+      if (scopeCount === 0)
+        throw Object.assign(new Error("scope does not match exactly one element"), { code: "scope_not_found" });
+      if (scopeCount > 1)
+        throw Object.assign(new Error("scope matches more than one element"), { code: "scope_ambiguous" });
+    }
+    const raw = await scope.ariaSnapshot({ mode: "ai" });
+    const nodes = parseSnapshot(raw);
+    await nameRows(this.page, nodes);
+    await nameContainers(this.page, nodes);
+    const view = prune(nodes, this.redactor, await passwordRefs(this.page, nodes));
+    const fullText = [...view.values()].map((node) => `  ${format(node, this.redactor)}`).join(`
+`);
+    const url = this.page.url();
+    let mode = "full";
+    let body = fullText;
+    if (!options.full && !options.scope && this.previous && this.previousUrl === url) {
+      const diff = diffViews(this.previous, view, this.redactor);
+      const text2 = diff.length ? diff.join(`
+`) : "(无变化)";
+      if (text2.length < fullText.length) {
+        mode = "diff";
+        body = text2;
+      }
+    }
+    if (!options.scope) {
+      this.previous = view;
+      this.previousUrl = url;
+      this.last = view;
+    }
+    if (options.table_text)
+      body += `
+${await this.tableText(scope)}`;
+    const text = `[page] ${this.redactor.url(url)} · ${this.redactor.text(await this.page.title())} [${mode}]
+${body}`;
+    return { mode, text, settled, stats: { raw: raw.length, pruned: fullText.length, sent: body.length } };
+  }
+  async tableText(scope) {
+    const rows = scope.locator("table tbody tr:visible, .el-table__body-wrapper tbody tr:visible");
+    const total = await rows.count();
+    const count = Math.min(total, 50);
+    const lines = [];
+    for (let i = 0;i < count; i++)
+      lines.push(`  table row: ${this.redactor.text((await rows.nth(i).innerText()).replace(/\s+/g, " ").trim())}`);
+    if (total > count)
+      lines.push(`  …（已截断，最多显示 50 行，共 ${total} 行）`);
+    return lines.length ? `[table_text]
+${lines.join(`
+`)}` : `[table_text]
+(无可见数据行)`;
+  }
+}
+
+// plugins/devflow-quality/runtime/playwright/src/explore/recorder.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+var safe = (value, label) => {
+  if (!/^[^/\\\x00-\x1f\x7f]+$/.test(value))
+    throw new Error(`${label} is invalid`);
+  return value;
+};
+function inferredRole(tag, type) {
+  if (tag === "button")
+    return "button";
+  if (tag === "a")
+    return "link";
+  if (tag === "select")
+    return "combobox";
+  if (tag === "textarea")
+    return "textbox";
+  if (tag !== "input")
+    return;
+  return { checkbox: "checkbox", radio: "radio", range: "slider" }[type ?? ""] ?? "textbox";
+}
+async function sameUnique(candidate, element) {
+  if (await candidate.count() !== 1)
+    return false;
+  const candidateHandle = await candidate.elementHandle();
+  if (!candidateHandle)
+    return false;
+  try {
+    return await element.evaluate((node, other) => node === other, candidateHandle);
+  } finally {
+    await candidateHandle.dispose();
+  }
+}
+
+class Recorder {
+  page;
+  view;
+  redactor;
+  feature;
+  environmentProfile;
+  startUrl;
+  steps = [];
+  explorationSteps = [];
+  secretVariables = new Set;
+  constructor(page, view, redactor, feature, environmentProfile, startUrl) {
+    this.page = page;
+    this.view = view;
+    this.redactor = redactor;
+    this.feature = feature;
+    this.environmentProfile = environmentProfile;
+    this.startUrl = startUrl;
+    const initial = new URL(startUrl);
+    this.steps.push({ action: "goto", url: `${initial.pathname}${initial.search}${initial.hash}` });
+  }
+  async unique(locator) {
+    return await locator.count() === 1;
+  }
+  async rowTarget(element, role, name) {
+    const row = element.locator("xpath=ancestor::tr[1]");
+    if (await row.count() !== 1)
+      return null;
+    const cells = row.locator(":scope > td:visible, :scope > th:visible");
+    for (let i = 0;i < await cells.count(); i++) {
+      const markerText = (await cells.nth(i).innerText()).replace(/\s+/g, " ").trim();
+      if (markerText.length < 2)
+        continue;
+      const rows = this.page.getByRole("row", { name: markerText, exact: false });
+      const inner = rows.getByRole(role, { name, exact: true });
+      if (await rows.count() === 1 && await sameUnique(inner, element)) {
+        return { locator: { within: { role: "row", name: markerText, exact: false }, role, name, exact: true }, data_dependent: true, reviewReasons: ["data_dependent_locator"] };
+      }
+    }
+    return null;
+  }
+  async contextTarget(node, role, name) {
+    const context = node.ctx.split(" > ").filter((item) => /^(dialog|alertdialog|form|navigation|banner|main|region)\b/.test(item)).pop();
+    if (!context)
+      return null;
+    const match = /^(\w+)(?: "([\s\S]*)")?$/.exec(context);
+    if (!match)
+      return null;
+    const contextRole = match[1];
+    const contextName = match[2];
+    const within = contextName ? { role: contextRole, name: contextName, exact: true } : { role: contextRole };
+    const root = contextName ? this.page.getByRole(contextRole, { name: contextName, exact: true }) : this.page.getByRole(contextRole);
+    const inner = root.getByRole(role, { name, exact: true });
+    if (await this.unique(root) && await sameUnique(inner, this.page.locator(`aria-ref=${node.ref}`)))
+      return { locator: { within, role, name, exact: true } };
+    return null;
+  }
+  async targetFor(ref) {
+    if (!this.view.hasRef(ref))
+      throw Object.assign(new Error(`unknown or stale ref ${ref}`), { code: "stale_ref" });
+    const node = this.view.node(ref);
+    if (!node)
+      throw Object.assign(new Error(`unknown or stale ref ${ref}`), { code: "stale_ref" });
+    const element = this.page.locator(`aria-ref=${ref}`);
+    if (await element.count() !== 1)
+      throw Object.assign(new Error(`ref ${ref} is not unique`), { code: "stale_ref" });
+    const testid = await element.getAttribute("data-testid");
+    if (testid && await sameUnique(this.page.getByTestId(testid), element))
+      return { locator: `testid:${testid}` };
+    const tag = await element.evaluate((item) => item.tagName.toLowerCase());
+    const role = node.role || inferredRole(tag, await element.getAttribute("type"));
+    const name = node.name;
+    if (role && name) {
+      const roleLocator = this.page.getByRole(role, { name, exact: true });
+      const rowTarget = await this.rowTarget(element, role, name);
+      if (rowTarget)
+        return rowTarget;
+      if (await sameUnique(roleLocator, element)) {
+        const inRow2 = await element.locator("xpath=ancestor::tr[1]").count() === 1;
+        return { locator: `role:${role}:${name}`, ...inRow2 ? { data_dependent: true, reviewReasons: ["row_scope_missing"] } : {} };
+      }
+      const within = await this.contextTarget(node, role, name);
+      if (within)
+        return within;
+    }
+    const ariaLabel = await element.getAttribute("aria-label");
+    if (ariaLabel && await sameUnique(this.page.getByLabel(ariaLabel, { exact: true }), element))
+      return { locator: `label:${ariaLabel}` };
+    const placeholder = await element.getAttribute("placeholder");
+    if (placeholder && await sameUnique(this.page.getByPlaceholder(placeholder, { exact: true }), element))
+      return { locator: `placeholder:${placeholder}` };
+    const candidates = [];
+    if (testid)
+      candidates.push(`testid:${testid}`);
+    if (role && name)
+      candidates.push(`role:${role}:${name}`);
+    if (placeholder)
+      candidates.push(`placeholder:${placeholder}`);
+    const inRow = await element.locator("xpath=ancestor::tr[1]").count() === 1;
+    return { needs_locator: true, candidates: candidates.map((candidate) => this.redactor.value(candidate)), ...inRow ? { data_dependent: true, reviewReasons: ["row_scope_missing"] } : {} };
+  }
+  recordPrepared(id, action, target, extra = {}) {
+    const step = { action, ...extra, locator: target.locator ?? "" };
+    this.steps.push(step);
+    this.explorationSteps.push({
+      id,
+      action,
+      role: typeof target.locator === "object" && target.locator ? target.locator.role : undefined,
+      ...target.needs_locator ? { needs_locator: true } : {},
+      ...target.candidates ? { candidates: target.candidates } : {},
+      ...target.data_dependent ? { data_dependent: true } : {},
+      ...target.reviewReasons ? { reviewReasons: target.reviewReasons } : {},
+      ...action.startsWith("assert_") ? { oracle_hint: "characterization" } : {}
+    });
+  }
+  recordAssertionReview(id, kind, expectedFromPage, circular, targetName, weak = false) {
+    const item = this.explorationSteps.find((step) => step.id === id);
+    if (item)
+      Object.assign(item, { ...expectedFromPage ? { expected_from_page: true } : {}, ...circular ? { circular: true } : {}, ...weak ? { reviewReasons: [...item.reviewReasons ?? [], "weak_assertion"] } : {} });
+  }
+  noteSecretVariable(name) {
+    this.secretVariables.add(name);
+  }
+  async writeDraft(name, tcId) {
+    const fileName = safe(name, "draft name").endsWith(".json") ? safe(name, "draft name") : `${safe(name, "draft name")}.json`;
+    const root = path.resolve(".devflow/planning/generated-cases", safe(this.feature, "feature"), "drafts");
+    await fs.mkdir(root, { recursive: true, mode: 448 });
+    const steps = this.steps.map((step, index) => ({ id: `s${String(index + 1).padStart(2, "0")}`, ...step }));
+    const metadata = this.explorationSteps.map((item, index) => ({ ...item, id: `s${String(index + 2).padStart(2, "0")}` }));
+    const review_items = [];
+    const reviewKeys = new Set;
+    const addReview = (item) => {
+      const key = `${item.step}\x00${item.reason}`;
+      if (!reviewKeys.has(key)) {
+        reviewKeys.add(key);
+        review_items.push(item);
+      }
+    };
+    for (const item of metadata) {
+      for (const reason of item.reviewReasons ?? [])
+        addReview({ step: item.id, reason });
+      if (item.needs_locator)
+        addReview({ step: item.id, reason: "needs_locator" });
+      if (item.expected_from_page)
+        addReview({ step: item.id, reason: "expected_from_page" });
+      if (item.circular)
+        addReview({ step: item.id, reason: "circular_assertion" });
+      if (item.action === "assert_visible" && ["button", "link"].includes(item.role ?? ""))
+        addReview({ step: item.id, reason: "weak_assertion" });
+    }
+    const business = metadata.some((item) => item.action?.startsWith("assert_") && item.action !== "assert_visible" && !item.circular);
+    if (!business)
+      addReview({ step: "case", reason: "no_business_assertion" });
+    const manual = [...new Set(review_items.filter((item) => item.reason !== "expected_from_page" && item.reason !== "data_dependent_locator").map((item) => item.step))];
+    const draft = {
+      cases: [{ tc_id: tcId ?? "TC-0000", name: name.replace(/\.json$/, ""), variables: Object.fromEntries([...this.secretVariables].map((key) => [key, { secret: key }])), data: { setup: [], cleanup: [] }, steps }],
+      exploration: { environment_profile: this.environmentProfile, start_url: this.redactor.url(this.startUrl), recorded_steps: steps.length, needs_manual: manual, review_items, steps: metadata }
+    };
+    const output = path.join(root, fileName);
+    const serialized = this.redactor.text(JSON.stringify(draft, null, 2));
+    await fs.writeFile(output, `${serialized}
+`, { mode: 384 });
+    return { path: output, manual, review_items };
+  }
+}
+
+// plugins/devflow-quality/runtime/playwright/src/explore/host.ts
+var browser = null;
+var context = null;
+var page = null;
+var view = null;
+var recorder = null;
+var redactor = null;
+var profileMemory = null;
+var idleTimer = null;
+var totalTimer = null;
+var inFlightRequests = 0;
+var requestStarted = null;
+var requestFinished = null;
+function installRequestCounter(currentContext) {
+  inFlightRequests = 0;
+  requestStarted = (request) => {
+    if (["fetch", "xhr", "document"].includes(request.resourceType()))
+      inFlightRequests++;
+  };
+  requestFinished = () => {
+    inFlightRequests = Math.max(0, inFlightRequests - 1);
+  };
+  currentContext.on("request", requestStarted);
+  currentContext.on("requestfinished", requestFinished);
+  currentContext.on("requestfailed", requestFinished);
+}
+function removeRequestCounter() {
+  if (context && requestStarted && requestFinished) {
+    context.off("request", requestStarted);
+    context.off("requestfinished", requestFinished);
+    context.off("requestfailed", requestFinished);
+  }
+  requestStarted = null;
+  requestFinished = null;
+  inFlightRequests = 0;
+}
+function reply(id, result) {
+  process.stdout.write(`${JSON.stringify({ id, ok: true, result })}
+`);
+}
+function failure(id, error) {
+  const item = error;
+  const code = item?.code ?? "host_error";
+  const message = redactor?.error(error) ?? (error instanceof Error ? error.message : String(error));
+  process.stdout.write(`${JSON.stringify({ id, ok: false, error: { code, message } })}
+`);
+}
+async function shutdown() {
+  if (idleTimer)
+    clearTimeout(idleTimer);
+  if (totalTimer)
+    clearTimeout(totalTimer);
+  idleTimer = null;
+  totalTimer = null;
+  removeRequestCounter();
+  await browser?.close().catch(() => {});
+  browser = null;
+  context = null;
+  page = null;
+  view = null;
+  recorder = null;
+  profileMemory = null;
+}
+function touch() {
+  if (idleTimer)
+    clearTimeout(idleTimer);
+  idleTimer = setTimeout(() => void shutdown(), 10 * 60 * 1000);
+}
+function session() {
+  if (!page || !view || !recorder || !redactor) {
+    throw Object.assign(new Error("explore session has not started"), { code: "session_not_started" });
+  }
+  return { page, view, recorder, redactor };
+}
+function absoluteUrl(raw, profile) {
+  return raw.startsWith("/") ? new URL(raw, profile.base_url).toString() : new URL(raw).toString();
+}
+function secretValue(key, profile) {
+  const envName = profile.secret_env?.[String(key)];
+  const value = envName ? process.env[envName] : undefined;
+  if (!value)
+    throw Object.assign(new Error(`secret ${String(key)} is unavailable`), { code: "secret_unavailable" });
+  return value;
+}
+async function settle(currentPage) {
+  const deadline = Date.now() + 8000;
+  await currentPage.waitForLoadState("domcontentloaded").catch(() => {});
+  if (!context)
+    return true;
+  let quietSince = 0;
+  let previousSnapshot = null;
+  while (Date.now() < deadline) {
+    if (inFlightRequests === 0) {
+      if (!quietSince)
+        quietSince = Date.now();
+      if (Date.now() - quietSince >= 500) {
+        const snapshot = await currentPage.ariaSnapshot({ mode: "ai" }).catch(() => "");
+        if (previousSnapshot !== null && snapshot === previousSnapshot)
+          return true;
+        previousSnapshot = snapshot;
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        continue;
+      }
+    } else {
+      quietSince = 0;
+      previousSnapshot = null;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return false;
+}
+async function doStart(request) {
+  if (page)
+    throw Object.assign(new Error("only one explore session is allowed"), { code: "session_exists" });
+  const environmentFile = process.env.DEVFLOW_EXPLORE_ENVIRONMENT_FILE;
+  if (!environmentFile || !path2.isAbsolute(environmentFile)) {
+    throw Object.assign(new Error("environment profile path is missing"), { code: "environment_profile_invalid" });
+  }
+  try {
+    const profile = JSON.parse(fs2.readFileSync(environmentFile, "utf8"));
+    profileMemory = profile;
+    const policy = buildPolicy(profile);
+    redactor = new Redactor;
+    for (const envName of Object.values(profile.secret_env ?? {})) {
+      const value = process.env[envName];
+      if (value)
+        redactor.add(value);
+    }
+    browser = await chromium.launch();
+    context = await browser.newContext();
+    installRequestCounter(context);
+    await new NetworkRecorder(redactor).install(context, policy);
+    page = await context.newPage();
+    const startUrl = absoluteUrl(String(request.params?.url ?? "/"), profile);
+    await page.goto(startUrl, { waitUntil: "domcontentloaded" });
+    const settled = await settle(page);
+    view = new ExplorerView(page, redactor);
+    recorder = new Recorder(page, view, redactor, String(request.params?.feature ?? "explore"), profile.profile ?? path2.basename(environmentFile, path2.extname(environmentFile)), startUrl);
+    totalTimer = setTimeout(() => void shutdown(), 60 * 60 * 1000);
+    reply(request.id, await view.observe({ full: true }, settled));
+  } catch (error) {
+    await shutdown();
+    throw error;
+  }
+}
+async function doAct(request) {
+  const current = session();
+  const ref = request.params?.ref;
+  const action = request.params?.action;
+  if (typeof ref !== "string" || typeof action !== "string") {
+    throw Object.assign(new Error("act requires ref and action"), { code: "invalid_params" });
+  }
+  const prepared = await current.recorder.targetFor(ref);
+  let value = request.params?.value;
+  let secretKey;
+  if (request.params?.value_from_secret !== undefined) {
+    secretKey = request.params.value_from_secret;
+    if (!profileMemory)
+      throw Object.assign(new Error("explore profile is unavailable"), { code: "environment_profile_invalid" });
+    value = secretValue(secretKey, profileMemory);
+    current.redactor.add(value);
+    current.recorder.noteSecretVariable(String(secretKey));
+  }
+  const locator = current.page.locator(`aria-ref=${ref}`);
+  switch (action) {
+    case "click":
+      await locator.click();
+      break;
+    case "fill":
+      await locator.fill(String(value ?? ""));
+      break;
+    case "check":
+      await locator.check();
+      break;
+    case "uncheck":
+      await locator.uncheck();
+      break;
+    case "select":
+      await locator.selectOption(value);
+      break;
+    case "press":
+      await locator.press(String(value ?? ""));
+      break;
+    default:
+      throw Object.assign(new Error(`unknown action ${action}`), { code: "invalid_params" });
+  }
+  const settled = await settle(current.page);
+  const id = `s${String(current.recorder.steps.length + 1).padStart(2, "0")}`;
+  const extra = {};
+  if (action === "fill" || action === "select" || action === "press") {
+    extra.value = secretKey === undefined ? current.redactor.text(String(value ?? "")) : `\${${String(secretKey)}}`;
+  }
+  current.recorder.recordPrepared(id, action, prepared, extra);
+  reply(request.id, { ...await current.view.observe({}, settled), settled });
+}
+async function doAssert(request) {
+  const current = session();
+  const ref = request.params?.ref;
+  const kind = request.params?.kind;
+  if (typeof ref !== "string" || typeof kind !== "string") {
+    throw Object.assign(new Error("assert requires ref and kind"), { code: "invalid_params" });
+  }
+  const prepared = await current.recorder.targetFor(ref);
+  const locator = current.page.locator(`aria-ref=${ref}`);
+  const requested = request.params?.expected;
+  let expected;
+  const match = request.params?.match === "contains" ? "contains" : "exact";
+  const normalizeWhitespace = request.params?.normalize_whitespace !== false;
+  const caseSensitive = request.params?.case_sensitive !== false;
+  if (kind === "visible") {
+    if (!await locator.isVisible())
+      throw Object.assign(new Error("element is not visible"), { code: "assertion_failed" });
+  } else if (kind === "value") {
+    const actual = await locator.inputValue();
+    expected = String(requested ?? actual);
+    if (actual !== expected)
+      throw Object.assign(new Error(`value assertion failed: expected ${current.redactor.text(expected)}`), { code: "assertion_failed" });
+  } else if (kind === "text") {
+    const actual = await locator.innerText();
+    expected = String(requested ?? actual.trim());
+    const matches = match === "contains" ? actual.includes(expected) : actual.trim() === expected;
+    if (!matches)
+      throw Object.assign(new Error(`text assertion failed: expected ${current.redactor.text(expected)}`), { code: "assertion_failed" });
+  } else if (kind === "each_text") {
+    const actual = await locator.allInnerTexts();
+    expected = typeof requested === "string" ? requested : actual[0]?.trim() ?? "";
+    const matches = actual.every((item) => match === "contains" ? item.includes(expected) : item.trim() === expected);
+    if (!matches)
+      throw Object.assign(new Error("each_text assertion failed"), { code: "assertion_failed" });
+  } else {
+    throw Object.assign(new Error(`unknown assertion kind ${kind}`), { code: "invalid_params" });
+  }
+  const action = kind === "visible" ? "assert_visible" : `assert_${kind}`;
+  const extra = {};
+  if (expected !== undefined)
+    extra.expected = expected;
+  if (kind !== "visible")
+    extra.match = match;
+  if (kind !== "visible") {
+    extra.normalize_whitespace = normalizeWhitespace;
+    extra.case_sensitive = caseSensitive;
+  }
+  current.recorder.recordPrepared(`s${String(current.recorder.steps.length + 1).padStart(2, "0")}`, action, prepared, extra);
+  const settled = await settle(current.page);
+  const targetName = current.view.node(ref)?.name ?? "";
+  const normalize = (value) => value.replace(/\s+/g, " ").trim();
+  const normalizedExpected = expected === undefined ? "" : normalize(expected);
+  const normalizedName = normalize(targetName);
+  const withinName = typeof prepared.locator === "object" && prepared.locator !== null ? String(prepared.locator.within?.name ?? "") : "";
+  const normalizedWithinName = normalize(withinName);
+  const circular = kind !== "visible" && Boolean(normalizedExpected && (normalizedName && (normalizedExpected.includes(normalizedName) || normalizedName.includes(normalizedExpected)) || normalizedWithinName && (normalizedExpected.includes(normalizedWithinName) || normalizedWithinName.includes(normalizedExpected))));
+  current.recorder.recordAssertionReview(`s${String(current.recorder.steps.length).padStart(2, "0")}`, kind, requested === undefined, circular, targetName, kind === "visible" && ["button", "link"].includes(current.view.node(ref)?.role ?? ""));
+  reply(request.id, { actual: current.redactor.value(kind === "each_text" ? await locator.allInnerTexts() : expected), view: await current.view.observe({}, settled), settled });
+}
+async function handle(request) {
+  touch();
+  try {
+    if (request.method === "start")
+      return await doStart(request);
+    if (request.method === "stop") {
+      await shutdown();
+      reply(request.id, { stopped: true });
+      return;
+    }
+    if (request.method === "act")
+      return await doAct(request);
+    if (request.method === "assert")
+      return await doAssert(request);
+    const current = session();
+    if (request.method === "observe") {
+      reply(request.id, await current.view.observe({ scope: request.params?.scope, full: request.params?.full, table_text: request.params?.table_text }));
+      return;
+    }
+    if (request.method === "draft") {
+      reply(request.id, await current.recorder.writeDraft(String(request.params?.name ?? "exploration"), request.params?.tc_id));
+      return;
+    }
+    throw Object.assign(new Error(`unknown method ${request.method}`), { code: "invalid_method" });
+  } catch (error) {
+    failure(request.id, error);
+  }
+}
+var input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+var requestQueue = Promise.resolve();
+input.on("line", (line) => {
+  try {
+    const request = JSON.parse(line);
+    requestQueue = requestQueue.then(() => handle(request)).catch((error) => process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`));
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+  }
+});
+process.on("SIGTERM", () => {
+  shutdown().finally(() => process.exit(0));
+});
+process.on("SIGINT", () => {
+  shutdown().finally(() => process.exit(0));
+});