@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/browser/src/shared-sandbox.ts

@@ -0,0 +1,53 @@
+/**
+ * Helpers for aligning browser policy with a Task 1 disposable sandbox workspace.
+ * No Playwright dependency — mounts and network attestation only.
+ */
+import type { BrowserDownloadOptions } from "./downloads.js";
+import type { BrowserNetworkPolicy } from "./network.js";
+import type { BrowserUploadOptions } from "./uploads.js";
+
+export interface SharedSandboxBrowserAlignment {
+  /** Host workspace root mirrored as sandbox `/workspace`. */
+  readonly workspaceRoot: string;
+  /** Host quarantine directory mirrored as sandbox `/downloads`. */
+  readonly downloadsRoot: string;
+  /**
+   * Required for real external browsing. Playwright routing remains defense in depth;
+   * the host proxy/firewall owns DNS and private egress.
+   */
+  readonly containedProxyAttestation?: BrowserNetworkPolicy["containedProxyAttestation"];
+  readonly approveDownloadRelease?: BrowserDownloadOptions["approveRelease"];
+  readonly allowLoopback?: boolean;
+  readonly allowPrivateHosts?: boolean;
+}
+
+export interface SharedSandboxBrowserOptions {
+  readonly networkPolicy: BrowserNetworkPolicy;
+  readonly uploads: BrowserUploadOptions;
+  readonly downloads: BrowserDownloadOptions;
+}
+
+/**
+ * Build browser manager/tool options that share the disposable sandbox workspace
+ * and download quarantine mounts. Callers still supply the Playwright Browser and
+ * must close the browser context before disposing the sandbox.
+ */
+export function createSharedSandboxBrowserOptions(input: SharedSandboxBrowserAlignment): SharedSandboxBrowserOptions {
+  if (!input.workspaceRoot || !input.downloadsRoot) {
+    throw new Error("workspaceRoot and downloadsRoot are required");
+  }
+  const networkPolicy: BrowserNetworkPolicy = {
+    requireContainedProxy: true,
+    allowLoopback: input.allowLoopback ?? false,
+    allowPrivateHosts: input.allowPrivateHosts ?? false,
+    ...(input.containedProxyAttestation ? { containedProxyAttestation: input.containedProxyAttestation } : {}),
+  };
+  return {
+    networkPolicy,
+    uploads: { roots: [input.workspaceRoot] },
+    downloads: {
+      quarantine: input.downloadsRoot,
+      ...(input.approveDownloadRelease ? { approveRelease: input.approveDownloadRelease } : {}),
+    },
+  };
+}

package/browser/src/snapshot.ts

@@ -0,0 +1,99 @@
+import { randomBytes } from "node:crypto";
+import { BrowserError } from "./errors.js";
+import type { ResolvedBrowserLimits } from "./limits.js";
+import { parseSnapshotRefs } from "./targets.js";
+import type { BrowserSnapshotResult, PlaywrightPage, SnapshotRefInfo } from "./types.js";
+
+export interface LiveSnapshot {
+  readonly snapshotId: string;
+  readonly pageId: string;
+  readonly url: string;
+  readonly title: string;
+  readonly ariaSnapshot: string;
+  readonly refs: ReadonlyMap<string, SnapshotRefInfo>;
+  readonly truncated: boolean;
+  readonly truncatedBy?: "bytes" | "refs" | "depth";
+  readonly createdAt: number;
+}
+
+export function createSnapshotId(): string {
+  return `snap_${randomBytes(8).toString("hex")}`;
+}
+
+export async function captureAriaSnapshot(page: PlaywrightPage, pageId: string, limits: ResolvedBrowserLimits): Promise<LiveSnapshot> {
+  let yaml: string;
+  try {
+    yaml = await page.ariaSnapshot({
+      mode: "ai",
+      depth: limits.maxSnapshotDepth,
+      timeout: limits.actionTimeoutMs,
+    });
+  } catch (error) {
+    throw new BrowserError("ERR_PRISM_BROWSER", `ariaSnapshot failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (typeof yaml !== "string") {
+    throw new BrowserError("ERR_PRISM_BROWSER", "ariaSnapshot returned a non-string value");
+  }
+
+  let truncated = false;
+  let truncatedBy: LiveSnapshot["truncatedBy"];
+  const bytes = Buffer.byteLength(yaml, "utf8");
+  if (bytes > limits.maxSnapshotBytes) {
+    yaml = Buffer.from(yaml, "utf8").subarray(0, limits.maxSnapshotBytes).toString("utf8");
+    // Avoid cutting mid-line for readability.
+    const lastNl = yaml.lastIndexOf("\n");
+    if (lastNl > 0) yaml = yaml.slice(0, lastNl);
+    truncated = true;
+    truncatedBy = "bytes";
+  }
+
+  const parsed = parseSnapshotRefs(yaml, limits.maxSnapshotRefs);
+  if (parsed.truncatedByRefs) {
+    truncated = true;
+    truncatedBy = truncatedBy ?? "refs";
+  }
+
+  let url = "";
+  let title = "";
+  try {
+    url = page.url();
+  } catch {
+    url = "";
+  }
+  try {
+    title = await page.title();
+  } catch {
+    title = "";
+  }
+
+  return {
+    snapshotId: createSnapshotId(),
+    pageId,
+    url: boundText(url, 2_048),
+    title: boundText(title, 1_024),
+    ariaSnapshot: yaml,
+    refs: parsed.refs,
+    truncated,
+    truncatedBy,
+    createdAt: Date.now(),
+  };
+}
+
+export function toSnapshotResult(snapshot: LiveSnapshot): BrowserSnapshotResult {
+  return {
+    snapshotId: snapshot.snapshotId,
+    pageId: snapshot.pageId,
+    url: snapshot.url,
+    title: snapshot.title,
+    ariaSnapshot: snapshot.ariaSnapshot,
+    refCount: snapshot.refs.size,
+    truncated: snapshot.truncated,
+    ...(snapshot.truncatedBy ? { truncatedBy: snapshot.truncatedBy } : {}),
+  };
+}
+
+function boundText(value: string, maxBytes: number): string {
+  const buf = Buffer.from(value, "utf8");
+  if (buf.byteLength <= maxBytes) return value;
+  return buf.subarray(0, maxBytes).toString("utf8");
+}

package/browser/src/targets.ts

@@ -0,0 +1,165 @@
+import { BrowserError } from "./errors.js";
+import type { BrowserTarget, PlaywrightLocator, PlaywrightPage, SnapshotRefInfo } from "./types.js";
+
+const REF_PATTERN = /^e\d+$/u;
+
+export function assertValidRef(ref: string): string {
+  if (typeof ref !== "string" || !REF_PATTERN.test(ref)) {
+    throw new BrowserError("ERR_PRISM_BROWSER_TARGET", `Invalid snapshot ref: ${String(ref).slice(0, 64)}`);
+  }
+  return ref;
+}
+
+/**
+ * Parse AI-mode aria snapshot YAML into a bounded ref table.
+ * Refs are snapshot-scoped; callers invalidate the table after mutations.
+ */
+export function parseSnapshotRefs(
+  ariaSnapshot: string,
+  maxRefs: number,
+): {
+  refs: Map<string, SnapshotRefInfo>;
+  truncatedByRefs: boolean;
+} {
+  const refs = new Map<string, SnapshotRefInfo>();
+  let truncatedByRefs = false;
+  for (const line of ariaSnapshot.split("\n")) {
+    const refMatch = /\[ref=(e\d+)\]/u.exec(line);
+    if (!refMatch) continue;
+    if (refs.size >= maxRefs) {
+      truncatedByRefs = true;
+      break;
+    }
+    const ref = refMatch[1]!;
+    if (refs.has(ref)) continue;
+    const roleMatch = /^\s*-\s+([A-Za-z][A-Za-z0-9_-]*)/u.exec(line);
+    const nameMatch = matchQuotedYamlString(line);
+    refs.set(ref, {
+      ref,
+      role: roleMatch?.[1],
+      name: nameMatch !== undefined ? unescapeYamlString(nameMatch) : undefined,
+    });
+  }
+  return { refs, truncatedByRefs };
+}
+
+// Linear quoted-string scanner replaces `/"((?:\\.|[^"\\])*)"/u` (CodeQL js/polynomial-redos, alert 3):
+// first unescaped-quote-delimited segment, undefined when absent or unterminated.
+function matchQuotedYamlString(line: string): string | undefined {
+  const open = line.indexOf('"');
+  if (open === -1) return undefined;
+  let i = open + 1;
+  while (i < line.length) {
+    const c = line[i];
+    if (c === "\\") {
+      i += 2;
+      continue;
+    }
+    if (c === '"') return line.slice(open + 1, i);
+    i += 1;
+  }
+  return undefined;
+}
+function unescapeYamlString(value: string): string {
+  return value.replace(/\\(["\\])/gu, "$1");
+}
+
+export function normalizeTarget(raw: unknown): BrowserTarget {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "target must be an object");
+  }
+  const obj = raw as Record<string, unknown>;
+  const keys = Object.keys(obj);
+  if ("selector" in obj || "evaluate" in obj) {
+    throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "selector/evaluate targets are not supported");
+  }
+  if (typeof obj.css === "string") {
+    if (keys.some((k) => k !== "css")) {
+      throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "css target must only include css");
+    }
+    return { css: obj.css };
+  }
+  if (typeof obj.xpath === "string") {
+    if (keys.some((k) => k !== "xpath")) {
+      throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "xpath target must only include xpath");
+    }
+    return { xpath: obj.xpath };
+  }
+  if (typeof obj.ref === "string") {
+    if (keys.some((k) => k !== "ref")) {
+      throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "ref target must only include ref");
+    }
+    return { ref: assertValidRef(obj.ref) };
+  }
+  if (typeof obj.role === "string") {
+    const name = obj.name === undefined ? undefined : String(obj.name);
+    const exact = obj.exact === true;
+    return { role: obj.role, ...(name !== undefined ? { name } : {}), exact };
+  }
+  if (typeof obj.label === "string") {
+    return { label: obj.label, exact: obj.exact === true };
+  }
+  if (typeof obj.testId === "string") {
+    return { testId: obj.testId };
+  }
+  if (typeof obj.text === "string") {
+    return { text: obj.text, exact: obj.exact === true };
+  }
+  throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "target must be one of ref, role(+name), label, testId, or text");
+}
+
+/**
+ * Resolve a target against a page. Ref targets require a live snapshot table and
+ * use Playwright's built-in `aria-ref=` selector engine (same mechanism as MCP).
+ */
+export async function resolveTargetLocator(
+  page: PlaywrightPage,
+  target: BrowserTarget,
+  refs: ReadonlyMap<string, SnapshotRefInfo> | undefined,
+  snapshotId: string | undefined,
+): Promise<PlaywrightLocator> {
+  if ("ref" in target) {
+    if (!snapshotId || !refs) {
+      throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "ref actions require a current snapshotId");
+    }
+    assertValidRef(target.ref);
+    if (!refs.has(target.ref)) {
+      throw new BrowserError("ERR_PRISM_BROWSER_TARGET", `Stale or unknown ref ${target.ref} for snapshot ${snapshotId}`);
+    }
+    return page.locator(`aria-ref=${target.ref}`);
+  }
+  if ("role" in target) {
+    return page.getByRole(target.role, {
+      ...(target.name !== undefined ? { name: target.name } : {}),
+      exact: target.exact === true,
+    });
+  }
+  if ("label" in target) {
+    return page.getByLabel(target.label, { exact: target.exact === true });
+  }
+  if ("testId" in target) {
+    return page.getByTestId(target.testId);
+  }
+  if ("css" in target) {
+    return page.locator(target.css);
+  }
+  if ("xpath" in target) {
+    return page.locator(`xpath=${target.xpath}`);
+  }
+  return page.getByText(target.text, { exact: target.exact === true });
+}
+
+/** Enforce strict single-match semantics before acting. */
+export async function requireUniqueLocator(locator: PlaywrightLocator): Promise<PlaywrightLocator> {
+  const count = await locator.count();
+  if (count === 0) {
+    throw new BrowserError("ERR_PRISM_BROWSER_TARGET", "No element matched the target");
+  }
+  if (count > 1) {
+    throw new BrowserError(
+      "ERR_PRISM_BROWSER_TARGET",
+      `Ambiguous target matched ${count} elements; refine role/name/label/testId or use a snapshot ref`,
+    );
+  }
+  return locator.first();
+}