@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/mcp/browser/page-scripts.ts

@@ -0,0 +1,129 @@
+/**
+ * The functions the agent's browser runs inside a page, as source text for
+ * the Chrome DevTools Protocol, shared by Forge's Browser and the headless
+ * one `frontera mcp` runs without Forge. They run in an isolated world except
+ * where noted, so the page's scripts can neither see nor change them. The
+ * agent's own script (`browser_evaluate`) runs in the page's world, wrapped
+ * by `evaluateWrapper`, never here.
+ */
+
+/** The element's own text, short. Called on the element. */
+export const ELEMENT_TEXT = `function () { return (this.innerText || this.value || this.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 300) }`
+
+/** Select what a field holds, so typed text replaces it. Called on the element. */
+export const SELECT_CONTENTS = `function () {
+  this.focus()
+  if (this.isContentEditable) { const r = document.createRange(); r.selectNodeContents(this); const s = getSelection(); s.removeAllRanges(); s.addRange(r) }
+  else if (typeof this.select === 'function') this.select()
+}`
+
+/** Put the caret at the end, so typed text is added. Called on the element. */
+export const CARET_TO_END = `function () {
+  this.focus()
+  if (typeof this.setSelectionRange === 'function' && typeof this.value === 'string') { try { this.setSelectionRange(this.value.length, this.value.length) } catch {} }
+}`
+
+/** The page's visible text, clipped. */
+export const PAGE_TEXT = `(document.body ? document.body.innerText : '').trim().slice(0, 4000)`
+
+/** Whether the element is in the document and drawn: some size, not hidden. Called on the element. */
+export const VISIBLE = `function () {
+  if (!this.isConnected) return false
+  const el = this.nodeType === 1 ? this : this.parentElement
+  if (!el) return false
+  const r = el.getBoundingClientRect()
+  const s = getComputedStyle(el)
+  return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none' && Number(s.opacity) !== 0
+}`
+
+/** Whether a CSS selector matches a drawn element: true, false, or { error } for a selector that is not one. */
+export function selectorVisible(selector: string): string {
+  return `((sel) => {
+  let el
+  try { el = document.querySelector(sel) } catch (e) { return { error: String(e && e.message || e) } }
+  if (!el) return false
+  const r = el.getBoundingClientRect()
+  const s = getComputedStyle(el)
+  return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none' && Number(s.opacity) !== 0
+})(${JSON.stringify(selector)})`
+}
+
+/** Whether the page's visible text holds the text (all of it, not the clipped PAGE_TEXT). */
+export function textPresent(text: string): string {
+  return `(document.body ? document.body.innerText : '').includes(${JSON.stringify(text)})`
+}
+
+/** Focus the element. Called on the element. */
+export const FOCUS = `function () { if (typeof this.focus === 'function') this.focus() }`
+
+/**
+ * Choose options in a <select> by value or label, as a person would, and
+ * tell the page (input, then change). Answers the chosen values, or { error }.
+ * Called on the element with the wanted values.
+ */
+export const SELECT_OPTIONS = `function (wanted) {
+  if (!this || this.tagName !== 'SELECT') return { error: 'not a <select>: click a custom list box open and click its option instead' }
+  if (this.disabled) return { error: 'the list is disabled' }
+  const options = [...this.options]
+  const picked = []
+  for (const w of wanted) {
+    const o = options.find((o) => o.value === w) || options.find((o) => o.label === w || o.text.trim() === w)
+    if (!o) return { error: 'no option "' + w + '"; there is ' + options.slice(0, 30).map((o) => JSON.stringify(o.label || o.value)).join(', ') }
+    if (o.disabled) return { error: 'the option "' + w + '" is disabled' }
+    picked.push(o)
+  }
+  if (picked.length > 1 && !this.multiple) return { error: 'the list takes one option' }
+  this.focus()
+  for (const o of options) o.selected = picked.includes(o)
+  this.dispatchEvent(new Event('input', { bubbles: true }))
+  this.dispatchEvent(new Event('change', { bubbles: true }))
+  return { values: picked.map((o) => o.value) }
+}`
+
+/**
+ * The agent's expression, run in the page's own world: a value, a promise,
+ * or a function (called with no arguments). The answer comes back as JSON
+ * text, clipped to `cap` characters, with what JSON cannot hold described
+ * (elements, functions, Maps, Sets, cycles) rather than lost.
+ */
+export function evaluateWrapper(expression: string, cap: number): string {
+  return `${answerJson(expression, cap, false)}()`
+}
+
+/** The agent's expression as an async function, of the element when `element` is set, answering JSON text clipped to `cap`. */
+function answerJson(expression: string, cap: number, element: boolean): string {
+  return `(async (${element ? 'element' : ''}) => {
+  let v = (${expression}
+  )
+  if (typeof v === 'function') v = v(${element ? 'element' : ''})
+  v = await v
+  const seen = new WeakSet()
+  const json = JSON.stringify(v === undefined ? null : v, (k, x) => {
+    if (typeof x === 'bigint') return x.toString() + 'n'
+    if (typeof x === 'function') return '[function ' + (x.name || 'anonymous') + ']'
+    if (typeof x === 'symbol') return x.toString()
+    if (x && typeof x === 'object') {
+      if (typeof Element !== 'undefined' && x instanceof Element) return '<' + x.tagName.toLowerCase() + (x.id ? '#' + x.id : '') + (x.classList && x.classList.length ? '.' + [...x.classList].slice(0, 3).join('.') : '') + '>'
+      if (typeof Node !== 'undefined' && x instanceof Node) return '[' + x.nodeName + ']'
+      if (x instanceof Map) return { '[Map]': [...x.entries()].slice(0, 200) }
+      if (x instanceof Set) return { '[Set]': [...x.values()].slice(0, 200) }
+      if (x instanceof Error) return { name: x.name, message: x.message }
+      if (seen.has(x)) return '[circular]'
+      seen.add(x)
+    }
+    return x
+  })
+  const text = json === undefined ? 'null' : json
+  return { type: v === undefined ? 'undefined' : v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v, json: text.slice(0, ${cap}), length: text.length }
+})`
+}
+
+/**
+ * The agent's expression run on an element (`browser_evaluate` with a ref),
+ * in the page's own world of the frame the element is in: a function is
+ * called with the element; anything else is answered as `evaluateWrapper`
+ * answers it. A function declaration for `Runtime.callFunctionOn` on the element.
+ */
+export function evaluateOnElement(expression: string, cap: number): string {
+  return `function () { return ${answerJson(expression, cap, true)}(this) }`
+}

package/src/mcp/browser/wait.ts

@@ -0,0 +1,73 @@
+/**
+ * What the agent can wait for (`browser_wait_for`, and `waitFor` on the
+ * reading tools), read the same way by Forge's Browser and the headless one
+ * `frontera mcp` runs without Forge.
+ */
+
+export interface WaitCondition {
+  text?: string
+  textGone?: string
+  selector?: string
+  /** For a selector or a ref: wait until it shows (default) or until it is gone or hidden. */
+  state?: 'visible' | 'hidden'
+  /** The ref's DOM node (`backendNodeId`). */
+  ref?: number
+  networkIdle?: boolean
+}
+
+export interface Wait {
+  condition: WaitCondition
+  timeoutMs: number
+  /** In words, for the answer. */
+  what: string
+}
+
+/** How long a wait lasts when the agent does not say, and at most. */
+export const WAIT_DEFAULT_MS = 10_000
+export const WAIT_MAX_MS = 60_000
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v.trim() : undefined)
+
+/**
+ * A wait from the agent's input, `null` when it asks for none, or why it is
+ * not one. `nodeForRef` names a ref's DOM node on the page (none before the
+ * tab has a page).
+ */
+export function parseWaitInput(input: Record<string, unknown> | undefined, nodeForRef: ((ref: string) => number | undefined) | null): Wait | { error: string } | null {
+  if (!input || typeof input !== 'object') return null
+  const condition: WaitCondition = {}
+  const what: string[] = []
+  const t = typeof input.text === 'string' && input.text ? input.text : undefined
+  const gone = typeof input.textGone === 'string' && input.textGone ? input.textGone : undefined
+  const selector = str(input.selector)
+  const ref = str(input.ref)
+  const hidden = input.state === 'hidden' || input.state === 'gone'
+  if (t !== undefined) {
+    condition.text = t
+    what.push(`text ${JSON.stringify(t)} to show`)
+  }
+  if (gone !== undefined) {
+    condition.textGone = gone
+    what.push(`text ${JSON.stringify(gone)} to go`)
+  }
+  if (selector) {
+    condition.selector = selector
+    condition.state = hidden ? 'hidden' : 'visible'
+    what.push(`${selector} to ${hidden ? 'go' : 'show'}`)
+  }
+  if (ref) {
+    const node = nodeForRef?.(ref)
+    if (node === undefined) return { error: `No element [ref=${ref}] on this page: take a browser_snapshot, or wait for text or a selector instead.` }
+    condition.ref = node
+    condition.state = hidden ? 'hidden' : 'visible'
+    what.push(`[ref=${ref}] to ${hidden ? 'go' : 'show'}`)
+  }
+  if (input.networkIdle === true) {
+    condition.networkIdle = true
+    what.push('the network to go quiet')
+  }
+  if (!what.length) return null
+  const timeout = Number(input.timeout)
+  const timeoutMs = Number.isFinite(timeout) && timeout > 0 ? Math.min(timeout * 1000, WAIT_MAX_MS) : WAIT_DEFAULT_MS
+  return { condition, timeoutMs, what: what.join(' and ') }
+}

package/src/mcp/forge-link.ts

@@ -0,0 +1,126 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, relative, isAbsolute } from 'node:path'
+
+import type { ToolResult } from './mcp-protocol'
+import type { ObserveRequest, PageObservation } from './page-observation'
+
+/**
+ * How `frontera mcp` reaches the Forge window's Browser. On start, and when a
+ * project is added, the Forge server writes `forge.json` into the project's
+ * `.frontera/local/` (mode 600) with its loopback port and a token made for
+ * that project on that start. The token reaches only the browser endpoint for
+ * this project, never the rest of Forge's API.
+ */
+
+export interface ForgeLink {
+  version: 1
+  port: number
+  token: string
+  pid: number
+  /** Forge's id for the project, so a stale file from another folder is never used. */
+  projectId: string
+  root: string
+  startedAt: string
+}
+
+export function forgeLinkPath(stateDir: string): string {
+  return join(stateDir, 'forge.json')
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    // EPERM: it runs, as another user.
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+function readLinkFile(file: string, isAlive: (pid: number) => boolean): ForgeLink | null {
+  if (!existsSync(file)) return null
+  try {
+    const link = JSON.parse(readFileSync(file, 'utf8')) as Partial<ForgeLink>
+    if (link.version !== 1 || typeof link.port !== 'number' || typeof link.token !== 'string' || typeof link.pid !== 'number') return null
+    return isAlive(link.pid) ? (link as ForgeLink) : null
+  } catch {
+    return null
+  }
+}
+
+const inside = (folder: string, root: string) => {
+  const rel = relative(root, folder)
+  return rel === '' || (!!rel && !rel.startsWith('..') && !isAbsolute(rel))
+}
+
+/** How many folders up a Forge project can sit above the folder `frontera mcp` started in. */
+const MAX_UP = 6
+
+/**
+ * The link to a running Forge for this project, or null. When the folder
+ * `frontera mcp` took for the project has no link of its own (it started in
+ * an App's folder, whose `.frontera` holds the App's render evidence), the
+ * Forge project the folder sits in is used: Forge is open for it, so the
+ * person's Browser is preferred over the headless one.
+ */
+export function readForgeLink(stateDir: string, isAlive: (pid: number) => boolean = alive): ForgeLink | null {
+  const own = readLinkFile(forgeLinkPath(stateDir), isAlive)
+  if (own) return own
+  // Only a project's own state folder (`<root>/.frontera/local`) says where the project is.
+  if (basename(stateDir) !== 'local' || basename(dirname(stateDir)) !== '.frontera') return null
+  const root = dirname(dirname(stateDir))
+  let dir = root
+  for (let i = 0; i < MAX_UP; i++) {
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+    const link = readLinkFile(join(dir, '.frontera', 'local', 'forge.json'), isAlive)
+    if (link) return typeof link.root === 'string' && inside(root, link.root) ? link : null
+  }
+  return null
+}
+
+/** Who is asking: the Forge session the harness runs in, when it runs in one. */
+export function forgeSession(env: NodeJS.ProcessEnv = process.env): string | null {
+  return env.FORGE_SESSION?.trim() || null
+}
+
+/** One request to Forge's browser endpoint; null when Forge is not reachable or has no window to show a page in. */
+async function forgeRequest(link: ForgeLink, body: Record<string, unknown>, opts: { timeoutMs?: number; fetchImpl?: typeof fetch }): Promise<{ status: number; body: unknown } | null> {
+  const doFetch = opts.fetchImpl ?? fetch
+  try {
+    const res = await doFetch(`http://127.0.0.1:${link.port}/mcp/browser`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-forge-mcp-token': link.token },
+      body: JSON.stringify({ projectId: link.projectId, ...body }),
+      // Forge bounds each action itself; a click outside the project waits for the person's answer.
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 150_000),
+    })
+    // 503: Forge runs without its window (the server alone), so nobody would see the page.
+    if (res.status === 503) return null
+    return { status: res.status, body: await res.json().catch(() => null) }
+  } catch (err) {
+    // Reached, but slower than the wait: say so rather than send the agent elsewhere.
+    if ((err as Error).name === 'TimeoutError') return { status: 504, body: { error: 'Forge did not answer in time. The page may still be loading; take a browser_snapshot to see where it is.' } }
+    return null
+  }
+}
+
+/**
+ * Run one browser tool in the Forge window. Answers null when Forge is not
+ * reachable, so the caller can fall back or refuse in words.
+ */
+export async function callForgeBrowser(link: ForgeLink, tool: string, input: Record<string, unknown>, opts: { session: string | null; timeoutMs?: number; fetchImpl?: typeof fetch } = { session: null }): Promise<ToolResult | null> {
+  const res = await forgeRequest(link, { session: opts.session, tool, input }, opts)
+  if (!res) return null
+  if (res.status >= 400) return { isError: true, content: [{ type: 'text', text: (res.body as { error?: string } | null)?.error ?? `Forge answered ${res.status}` }] }
+  return res.body as ToolResult
+}
+
+/** Open a page in a Forge Browser tab the person can see, let it settle, and observe it. */
+export async function observeInForge(link: ForgeLink, req: ObserveRequest, opts: { session: string | null; label?: string; fetchImpl?: typeof fetch }): Promise<PageObservation | null> {
+  const res = await forgeRequest(link, { session: opts.session, tool: 'observe', input: { ...req, label: opts.label } }, { timeoutMs: 150_000, fetchImpl: opts.fetchImpl })
+  if (!res) return null
+  if (res.status >= 400) throw new Error((res.body as { error?: string } | null)?.error ?? `Forge answered ${res.status}`)
+  return res.body as PageObservation
+}

package/src/mcp/headless.ts

@@ -0,0 +1,199 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+import { AXE_RUN, summarizeA11y } from './a11y-scan'
+import { credentialsIn, redactDeep, redactWith } from './browser/credentials'
+import type { PageObservation, ObserveRequest } from './page-observation'
+
+/**
+ * The browser `frontera mcp` uses when Forge is not running (a plain
+ * terminal, an IDE, CI): headless Chromium through Playwright. One Chromium
+ * serves the whole MCP server process: `app_render`'s observations (each in
+ * a context of its own, closed after) and the `browser_*` tools' session
+ * (`browser/headless-session.ts`). It closes after a while unused.
+ *
+ * Chromium is Playwright's pinned build, downloaded on first use. A machine
+ * that already has one (`FRONTERA_CHROMIUM_PATH`, or a build under
+ * `PLAYWRIGHT_BROWSERS_PATH`) uses it instead.
+ */
+
+type Playwright = typeof import('playwright-core')
+export type HeadlessChromium = import('playwright-core').Browser
+
+function loadPlaywright(): Playwright {
+  const require = createRequire(import.meta.url)
+  try {
+    return require('playwright-core') as Playwright
+  } catch {
+    throw new Error('The headless browser is not installed with this CLI (playwright-core). Open the project in Forge to render it, or reinstall the CLI.')
+  }
+}
+
+/** A Chromium already on this machine, newest build first. */
+export function installedChromium(env: NodeJS.ProcessEnv = process.env): string | null {
+  if (env.FRONTERA_CHROMIUM_PATH && existsSync(env.FRONTERA_CHROMIUM_PATH)) return env.FRONTERA_CHROMIUM_PATH
+  const root = env.PLAYWRIGHT_BROWSERS_PATH
+  if (!root || !existsSync(root)) return null
+  const builds = readdirSync(root)
+    .filter((d) => /^chromium(_headless_shell)?-\d+$/.test(d))
+    .sort((a, b) => Number(b.split('-').pop()) - Number(a.split('-').pop()))
+  for (const build of builds) {
+    for (const exe of ['chrome-linux/chrome', 'chrome-linux/headless_shell', 'chrome-mac/Chromium.app/Contents/MacOS/Chromium', 'chrome-headless-shell-linux64/chrome-headless-shell']) {
+      const path = join(root, build, exe)
+      if (existsSync(path)) return path
+    }
+  }
+  return null
+}
+
+/** Download Playwright's pinned headless Chromium, once. */
+function installChromium(): void {
+  const require = createRequire(import.meta.url)
+  const cli = join(dirname(require.resolve('playwright-core/package.json')), 'cli.js')
+  const result = spawnSync(process.execPath, [cli, 'install', 'chromium-headless-shell'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 10 * 60_000 })
+  if (result.status !== 0) throw new Error(`Chromium could not be downloaded for the headless browser: ${String(result.stderr ?? '').trim().slice(-400) || 'no output'}`)
+}
+
+async function launch(pw: Playwright): Promise<HeadlessChromium> {
+  // Frames from another site in a process of their own, as in Forge and a desktop Chrome: an App embedded in Studio is read and driven the same way in both.
+  const args = ['--no-sandbox', '--disable-dev-shm-usage', '--site-per-process']
+  try {
+    return await pw.chromium.launch({ args })
+  } catch (err) {
+    if (!/Executable doesn't exist|browserType\.launch/i.test((err as Error).message)) throw err
+    const local = installedChromium()
+    if (local) return pw.chromium.launch({ args, executablePath: local })
+    installChromium()
+    return pw.chromium.launch({ args })
+  }
+}
+
+/** How long the shared Chromium stays up once nothing holds it: renders in a row reuse it. */
+export const LINGER_MS = 60_000
+
+let shared: Promise<HeadlessChromium> | null = null
+let users = 0
+let idleTimer: ReturnType<typeof setTimeout> | null = null
+
+/**
+ * The process's Chromium, launched on first use. Each caller holds it while
+ * it works (`release` when done); once nobody holds it for `LINGER_MS`
+ * it closes, and the next call launches it again.
+ */
+export async function acquireChromium(): Promise<{ browser: HeadlessChromium; release: () => void }> {
+  users++
+  if (idleTimer) {
+    clearTimeout(idleTimer)
+    idleTimer = null
+  }
+  try {
+    if (!shared) {
+      const launching = launch(loadPlaywright())
+      shared = launching
+      launching.then(
+        (b) => b.on('disconnected', () => {
+          if (shared === launching) shared = null
+        }),
+        () => {
+          if (shared === launching) shared = null
+        },
+      )
+    }
+    const browser = await shared
+    let released = false
+    return {
+      browser,
+      release: () => {
+        if (released) return
+        released = true
+        users--
+        if (users > 0) return
+        idleTimer = setTimeout(() => {
+          idleTimer = null
+          if (users > 0 || !shared) return
+          const closing = shared
+          shared = null
+          void closing.then((b) => b.close()).catch(() => {})
+        }, LINGER_MS)
+        idleTimer.unref?.()
+      },
+    }
+  } catch (err) {
+    users--
+    throw err
+  }
+}
+
+/** Open a page headless, let it settle, and report what a person would have seen and the console would have said. */
+export async function observeHeadless(req: ObserveRequest): Promise<PageObservation> {
+  const { browser, release } = await acquireChromium()
+  const context = await browser.newContext({ viewport: { width: req.width ?? 1440, height: req.height ?? 900 } }).catch((err) => {
+    release()
+    throw err
+  })
+  try {
+    const page = await context.newPage()
+    const console: PageObservation['console'] = []
+    const failed: PageObservation['failedRequests'] = []
+    const requests: PageObservation['requests'] = []
+    // Credentials the page's addresses carry (an App frame's launch token): never in the observation.
+    const secrets = new Map<string, string>()
+    const note = (url: string) => {
+      for (const c of credentialsIn(url)) if (!secrets.has(c.secret)) secrets.set(c.secret, c.label)
+    }
+    const shown = (url: string) => redactWith(url, secrets).slice(0, 300)
+    page.on('request', (r) => note(r.url()))
+    page.on('framenavigated', (f) => note(f.url()))
+    page.on('console', (m) => {
+      const level = m.type()
+      if (level === 'error' || level === 'warning') console.push({ level: level === 'warning' ? 'warning' : 'error', text: m.text().slice(0, 500) })
+    })
+    page.on('pageerror', (e) => console.push({ level: 'error', text: `Uncaught ${String(e?.message ?? e).slice(0, 500)}` }))
+    // Redacted before clipping, so a clipped address cannot keep half a token.
+    page.on('requestfailed', (r) => failed.push({ url: shown(r.url()), method: r.method(), reason: r.failure()?.errorText ?? 'failed' }))
+    page.on('response', (r) => {
+      const request = r.request()
+      requests.push({ url: shown(r.url()), method: request.method(), status: r.status(), type: request.resourceType() })
+      if (r.status() >= 400) failed.push({ url: shown(r.url()), method: request.method(), reason: `HTTP ${r.status()}` })
+    })
+    let navigationError: string | null = null
+    try {
+      await page.goto(req.url, { waitUntil: 'domcontentloaded', timeout: 45_000 })
+      // Never fatal: a dev server holding a websocket open (HMR) never goes idle.
+      await page.waitForLoadState('networkidle', { timeout: req.settleMs ?? 8_000 }).catch(() => {})
+      if (req.waitForText) await page.getByText(req.waitForText).first().waitFor({ timeout: 15_000 }).catch(() => {})
+    } catch (err) {
+      navigationError = String((err as Error)?.message ?? err).slice(0, 500)
+    }
+    let a11y: PageObservation['a11y'] = null
+    if (req.a11yScript && !navigationError) {
+      try {
+        await page.addScriptTag({ content: req.a11yScript })
+        a11y = summarizeA11y(await page.evaluate(AXE_RUN))
+      } catch {
+        // A page that refuses the script (a strict CSP) is reported without a scan.
+      }
+    }
+    const png = await page.screenshot({ fullPage: Boolean(req.fullPage) })
+    const title = await page.title().catch(() => '')
+    const text = await page.locator('body').innerText({ timeout: 2_000 }).catch(() => '')
+    const { screenshot, ...seen } = {
+      url: page.url(),
+      title,
+      text: String(text ?? '').trim().slice(0, 4_000),
+      console,
+      failedRequests: failed,
+      requests,
+      navigationError,
+      screenshot: Buffer.from(png).toString('base64'),
+      where: 'headless' as const,
+      a11y,
+    }
+    return { ...redactDeep(seen, secrets), screenshot }
+  } finally {
+    await context.close().catch(() => {})
+    release()
+  }
+}