@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/main.ts

@@ -3,7 +3,9 @@ import { parseArgs } from './args'
 import { resolveCredential } from './config'
 import { findProjectRoot } from './context'
 import { CliError, UsageError } from './errors'
-import { EXIT, sessionLaneFailure, sessionLaneRefusal } from './exit'
+import { EXIT, sessionLaneFailure, sessionLaneRefusal, type ExitCode } from './exit'
+import { actAsLocalPersona, listPersonas, localPersonaHint, redact } from './local/local-personas'
+import { localRuntimeAt } from './local/local-runtime-target'
 import { resolveOrganization, setSelectedOrganization } from './organization'
 import { createOutput, type OutputMode } from './output'
 import { readProject } from './project'
@@ -45,6 +47,20 @@ import type { AppProject } from './context'
  * on top — so it gets `-dev`, which is what stops a bug report from naming a
  * version whose code the reporter is not running.
  */
+/**
+ * A key refused on a command that acts as a person, against the project's
+ * own local runtime: told to act as a local persona (`--as`), with the
+ * personas it has, never to fetch a person's session token. Null anywhere
+ * else, or for any other failure, to keep it as it is.
+ */
+async function onLocalRuntime(failure: CliError, meta: { noun: string; verb: string; authLane?: string }, cwd: string, credential: { apiUrl: string; token: string }): Promise<CliError | null> {
+  if (meta.authLane !== 'session' || !credential.token.startsWith('sk-') || !credential.apiUrl) return null
+  const local = localRuntimeAt(cwd, credential.apiUrl)
+  if (!local) return null
+  const personas = await listPersonas(local.serviceUrl, local.creds)
+  return new CliError(failure.message, { code: failure.code, hint: localPersonaHint(meta, personas), cause: failure })
+}
+
 async function resolveVersion(): Promise<string> {
   const stamped = process.env.FRONTERA_CLI_VERSION
   if (stamped) return stamped
@@ -134,7 +150,7 @@ async function main(): Promise<number> {
 
   const args = direct ? [maybeVerb, ...rest].filter((a): a is string => a !== undefined) : rest
   const spec = flagsFor(command.meta)
-  const { positional, flags } = parseArgs(args, spec, aliasesFor(command.meta))
+  const { positional, flags, repeated } = parseArgs(args, spec, aliasesFor(command.meta))
 
   if (flags.help === true) {
     return emit(describeCommand(command.meta), () => renderCommandHelp(command.meta))
@@ -144,6 +160,10 @@ async function main(): Promise<number> {
   const output = createOutput(mode, { quiet: flags.quiet === true })
   // Read by the failure path: which credential was refused decides the hint.
   let token = ''
+  // Where that credential was sent: the project's own local runtime words a refusal differently.
+  let apiUrlUsed = ''
+  // A local persona's session (`--as`): redacted from anything a failure says.
+  let personaToken = ''
 
   try {
     // Reserved commands fail BEFORE anything else — no credential is
@@ -201,19 +221,37 @@ async function main(): Promise<number> {
     // project are always read from one place. Two directories would mean
     // `--dir ../other-customer` could edit one customer's app with another
     // customer's key.
-    const credential = command.meta.offline
+    let credential = command.meta.offline
       ? { apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : (process.env.FRONTERA_API_URL ?? ''), token: '' }
       : await resolveCredential(
           {
             apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : undefined,
             profile: typeof flags.profile === 'string' ? flags.profile : undefined,
+            // In a local project, an organization command takes the runtime's organization key.
+            organization: commandScope(command.meta) === 'organization' && command.meta.noun !== 'auth' && command.meta.noun !== 'kit',
           },
           { cwd },
         )
     token = credential.token
+    apiUrlUsed = credential.apiUrl
 
-    const workspaceFlag = typeof flags.workspace === 'string' ? flags.workspace.trim() : undefined
-    const orgFlag = typeof flags.org === 'string' ? flags.org.trim() : undefined
+    let workspaceFlag = typeof flags.workspace === 'string' ? flags.workspace.trim() : undefined
+    let orgFlag = typeof flags.org === 'string' ? flags.org.trim() : undefined
+
+    // `--as <persona>`: a local persona's session for this one command, on the project's
+    // own local runtime only (`local-personas.ts`). Its token is never printed.
+    if (typeof flags.as === 'string' && !command.meta.offline) {
+      const acting = await actAsLocalPersona({ meta: command.meta, cwd, apiUrl: credential.apiUrl, wanted: flags.as })
+      if ((workspaceFlag && workspaceFlag !== acting.workspaceId) || (orgFlag && orgFlag !== acting.organizationId)) {
+        throw new UsageError('--as acts in the local runtime\'s own workspace', 'drop --workspace and --org')
+      }
+      personaToken = acting.token
+      credential = { apiUrl: credential.apiUrl, token: acting.token }
+      token = acting.token
+      workspaceFlag = acting.workspaceId
+      orgFlag = acting.organizationId
+      output.note(`acting as ${acting.persona.displayName} (${acting.persona.key}), a local persona`)
+    }
 
     /**
      * `--workspace` is global — same reasoning as `--profile`: an escape hatch
@@ -258,7 +296,7 @@ async function main(): Promise<number> {
         ?? (missingArg
           ? null
           : unaddressedWorkspaceRefusal({ meta: command.meta, token: credential.token, workspace: workspaceFlag }))
-      if (refusal) throw refusal
+      if (refusal) throw (await onLocalRuntime(refusal, command.meta, cwd, credential)) ?? refusal
     }
 
     /**
@@ -294,17 +332,20 @@ async function main(): Promise<number> {
       token: credential.token,
       positional,
       flags,
+      repeated,
       output,
       project,
       ...(workspaceFlag ? { workspaceId: workspaceFlag } : {}),
     })
 
-    output.render(result.data, () => result.text)
-    return EXIT.OK
+    output.render(personaToken ? redact(result.data, personaToken) : result.data, () => (personaToken ? redact(result.text, personaToken) : result.text))
+    return (result.exitCode ?? EXIT.OK) as ExitCode
   } catch (err) {
     // A key on a session-lane command: one recovery for every such noun,
     // rather than each API client rewording its own 401/403.
-    return output.fail(sessionLaneFailure(command.meta, token, err) ?? err)
+    const laneFailure = sessionLaneFailure(command.meta, token, err)
+    const failure = (laneFailure && (await onLocalRuntime(laneFailure, command.meta, typeof flags.dir === 'string' ? flags.dir : process.cwd(), { apiUrl: apiUrlUsed, token }).catch(() => null))) ?? laneFailure ?? err
+    return output.fail(personaToken ? redact(failure, personaToken) : failure)
   }
 }
 

package/src/mcp/a11y-scan.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+
+/**
+ * A basic accessibility scan of a rendered page (design 2026-10-18 §6):
+ * axe-core's WCAG 2 A and AA rules, run in the page `app_render` opened, in
+ * Forge's tab or headless. What it finds is kept with the render evidence,
+ * and a deployment's Accessibility check reads it: serious and critical
+ * findings fail it; the rest are listed.
+ */
+
+export interface A11yFinding {
+  id: string
+  impact: 'minor' | 'moderate' | 'serious' | 'critical' | null
+  help: string
+  nodes: number
+  /** The first element it found, as a selector. */
+  target: string | null
+}
+
+export interface A11yResult {
+  /** Serious and critical findings: what fails the check. */
+  violations: number
+  findings: A11yFinding[]
+}
+
+let source: string | null | undefined
+
+/** axe-core's script, read once; null when the CLI was installed without it. */
+export function axeSource(): string | null {
+  if (source !== undefined) return source
+  try {
+    source = readFileSync(createRequire(import.meta.url).resolve('axe-core/axe.min.js'), 'utf8')
+  } catch {
+    source = null
+  }
+  return source
+}
+
+/** Run in the page after axe's script: the violations, in plain data. */
+export const AXE_RUN = `(async () => {
+  const r = await axe.run(document, { runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] }, resultTypes: ['violations'] })
+  return r.violations.map((v) => ({ id: v.id, impact: v.impact || null, help: v.help, nodes: v.nodes.length, target: v.nodes[0] && v.nodes[0].target ? v.nodes[0].target.join(' ') : null }))
+})()`
+
+/** The scan's findings as the evidence keeps them: worst first, at most 20. */
+export function summarizeA11y(raw: unknown): A11yResult | null {
+  if (!Array.isArray(raw)) return null
+  const rank = { critical: 0, serious: 1, moderate: 2, minor: 3 } as const
+  const findings = raw
+    .filter((f): f is A11yFinding => !!f && typeof (f as A11yFinding).id === 'string')
+    .map((f) => ({ id: f.id, impact: f.impact ?? null, help: String(f.help ?? '').slice(0, 200), nodes: Number(f.nodes) || 0, target: f.target ? String(f.target).slice(0, 200) : null }))
+    .sort((a, b) => (rank[a.impact ?? 'minor'] ?? 4) - (rank[b.impact ?? 'minor'] ?? 4))
+  return { violations: findings.filter((f) => f.impact === 'serious' || f.impact === 'critical').length, findings: findings.slice(0, 20) }
+}

package/src/mcp/browser/ax-snapshot.ts

@@ -0,0 +1,181 @@
+/**
+ * A page's accessibility tree as the coding agent reads it, in the shape
+ * Playwright MCP's snapshot uses: one line per meaningful node, indented by
+ * depth, with a ref for each element the agent can click or type into.
+ * Built from Chrome's `Accessibility.getFullAXTree`.
+ *
+ * Shared by both browsers the coding agent drives: Forge's (which re-exports
+ * this module) and the headless one `frontera mcp` runs without Forge, so a
+ * snapshot and its refs read the same in either.
+ */
+
+export interface AxValue {
+  type?: string
+  value?: unknown
+}
+
+export interface AxNode {
+  nodeId: string
+  ignored?: boolean
+  role?: AxValue
+  name?: AxValue
+  value?: AxValue
+  description?: AxValue
+  properties?: Array<{ name: string; value: AxValue }>
+  childIds?: string[]
+  parentId?: string
+  backendDOMNodeId?: number
+}
+
+/** Roles that only group: their children are shown in their place. */
+const TRANSPARENT = new Set(['generic', 'none', 'presentation', 'InlineTextBox', 'LineBreak', 'RootWebArea', 'WebArea', 'Section', 'group'])
+
+/** Roles an agent acts on; they get a ref. */
+const ACTIONABLE = new Set([
+  'button', 'link', 'textbox', 'searchbox', 'combobox', 'checkbox', 'radio', 'switch', 'slider', 'spinbutton',
+  'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'tab', 'treeitem', 'listbox', 'gridcell', 'row', 'columnheader',
+  'textarea', 'select', 'summary', 'disclosure triangle',
+])
+
+const SHOWN_PROPERTIES = ['level', 'checked', 'pressed', 'expanded', 'selected', 'disabled', 'required', 'invalid', 'readonly'] as const
+
+const MAX_LINES = 1_200
+
+function text(v: AxValue | undefined): string {
+  if (v?.value === undefined || v.value === null) return ''
+  return String(v.value).replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * A frame's tree read into the page's (an App embedded in Studio): shown under
+ * its <iframe> element, keyed there by that element's accessibility node id.
+ */
+export interface FrameContent {
+  nodes: AxNode[]
+  /** The frame's address, without its query. */
+  url: string
+  /** The number an element of this frame is named by (its handle), from its DOM node. */
+  handleOf: (backendDOMNodeId: number) => number
+  frames?: Map<string, FrameContent | { error: string }>
+}
+
+export interface Snapshot {
+  /** The tree as text. */
+  text: string
+  /** Each ref's DOM node (a handle, for an element in a frame), for the actions. */
+  refs: Map<string, number>
+  /** Each ref's role and name, to find the element again after the page changes. */
+  labels: Map<string, { role: string; name: string }>
+  truncated: boolean
+}
+
+/**
+ * `refFor` keeps refs stable: the tab hands out one ref per DOM node for as
+ * long as the document lives, so e1 stays the same element across snapshots
+ * and actions until the page navigates. Without it, refs count from e1.
+ */
+export function formatSnapshot(
+  nodes: AxNode[],
+  opts: { url: string; title: string; refPrefix?: string; refFor?: (backendDOMNodeId: number) => string; frames?: Map<string, FrameContent | { error: string }> },
+): Snapshot {
+  const refs = new Map<string, number>()
+  const labels = new Map<string, { role: string; name: string }>()
+  const lines: string[] = [`- Page URL: ${opts.url}`, `- Page title: ${opts.title}`, '- Snapshot:']
+  let counter = 0
+  let truncated = false
+
+  interface Tree {
+    byId: Map<string, AxNode>
+    handleOf: (backendDOMNodeId: number) => number
+    frames: Map<string, FrameContent | { error: string }> | undefined
+  }
+  const treeOf = (ns: AxNode[], handleOf: Tree['handleOf'], frames: Tree['frames']): { tree: Tree; root: AxNode | undefined } => {
+    const byId = new Map(ns.map((n) => [n.nodeId, n]))
+    return { tree: { byId, handleOf, frames }, root: ns.find((n) => !n.parentId || !byId.has(n.parentId)) ?? ns[0] }
+  }
+
+  const visit = (tree: Tree, node: AxNode, depth: number, parentName: string) => {
+    if (lines.length >= MAX_LINES) {
+      truncated = true
+      return
+    }
+    const role = text(node.role)
+    const name = text(node.name)
+    const kids = (node.childIds ?? []).map((id) => tree.byId.get(id)).filter((n): n is AxNode => !!n)
+    // Text that only repeats its parent's name adds nothing.
+    if (role === 'StaticText') {
+      if (name && name !== parentName) lines.push(`${'  '.repeat(depth)}- text: ${JSON.stringify(name)}`)
+      return
+    }
+    if (node.ignored || TRANSPARENT.has(role) || !role) {
+      for (const k of kids) visit(tree, k, depth, parentName)
+      return
+    }
+    const props = (node.properties ?? [])
+      .filter((p) => (SHOWN_PROPERTIES as readonly string[]).includes(p.name) && p.value.value !== false && p.value.value !== 'false' && p.value.value !== undefined)
+      .map((p) => (p.value.value === true || p.value.value === 'true' ? p.name : `${p.name}=${String(p.value.value)}`))
+    let ref = ''
+    if (node.backendDOMNodeId !== undefined && (ACTIONABLE.has(role) || props.includes('focusable'))) {
+      const handle = tree.handleOf(node.backendDOMNodeId)
+      const id = opts.refFor ? opts.refFor(handle) : `${opts.refPrefix ?? 'e'}${++counter}`
+      refs.set(id, handle)
+      labels.set(id, { role, name })
+      ref = id
+    }
+    const value = text(node.value)
+    const frame = tree.frames?.get(node.nodeId)
+    const bits = [`- ${role}`, name ? JSON.stringify(name) : '', ...props.map((p) => `[${p}]`), ref ? `[ref=${ref}]` : '', frame && 'url' in frame ? `[frame=${frame.url}]` : ''].filter(Boolean).join(' ')
+    lines.push(`${'  '.repeat(depth)}${bits}${value && value !== name ? `: ${JSON.stringify(value.slice(0, 200))}` : ''}`)
+    for (const k of kids) visit(tree, k, depth + 1, name)
+    // An embedded frame (an App in Studio): its page, under its <iframe>, with refs that act inside it.
+    if (frame && 'error' in frame) lines.push(`${'  '.repeat(depth + 1)}- text: ${JSON.stringify(`(the frame could not be read: ${frame.error})`)}`)
+    else if (frame) {
+      const inner = treeOf(frame.nodes, frame.handleOf, frame.frames)
+      if (inner.root) visit(inner.tree, inner.root, depth + 1, name)
+    }
+  }
+
+  const top = treeOf(nodes, (n) => n, opts.frames)
+  if (top.root) visit(top.tree, top.root, 0, '')
+  if (truncated) lines.push(`- … the page has more; the snapshot stops at ${MAX_LINES} lines`)
+  return { text: lines.join('\n'), refs, labels, truncated }
+}
+
+/** After the page changed, the ref in a new snapshot for the same element: same role and name, the first one. */
+export function findAgain(label: { role: string; name: string }, snapshot: Snapshot): string | null {
+  for (const [ref, l] of snapshot.labels) if (l.role === label.role && l.name === label.name) return ref
+  return null
+}
+
+/**
+ * One document's refs: a DOM node keeps the ref it first got for as long as
+ * the document lives, so a ref from any snapshot of the page still names the
+ * same element after the agent's actions. Cleared when the tab navigates to
+ * another document (the nodes are gone with it).
+ */
+export class RefBook {
+  private byNode = new Map<number, string>()
+  private byRef = new Map<string, number>()
+  private counter = 0
+
+  constructor(private readonly prefix = 'e') {}
+
+  readonly refFor = (backendDOMNodeId: number): string => {
+    const known = this.byNode.get(backendDOMNodeId)
+    if (known) return known
+    const ref = `${this.prefix}${++this.counter}`
+    this.byNode.set(backendDOMNodeId, ref)
+    this.byRef.set(ref, backendDOMNodeId)
+    return ref
+  }
+
+  node(ref: string): number | undefined {
+    return this.byRef.get(ref)
+  }
+
+  reset(): void {
+    this.byNode.clear()
+    this.byRef.clear()
+    this.counter = 0
+  }
+}

package/src/mcp/browser/credentials.ts

@@ -0,0 +1,78 @@
+/**
+ * Credentials that ride in a local address, which the coding agent's browser
+ * keeps out of everything it reports (tab addresses, the network list, the
+ * console, snapshots, script results, render observations), in Forge's
+ * Browser and the headless one alike:
+ *
+ * - Studio's sign-in link, `?token=`: swapped for a cookie, then redirected away from.
+ * - An App's launch token, `?t=` on the App's frame address: a signed asset
+ *   token (its app, user and version, then a signature) that loads that App's
+ *   build as that person until it expires. The App's first page hands it to
+ *   its worker and drops it from the address, but the first request carries it.
+ * - The usual names an address carries a credential under (`access_token`,
+ *   `code`, `session`, `handoff`…), in the query or the fragment.
+ *
+ * Only on this machine's addresses: a site elsewhere is the person's own
+ * business, and its parameters are not this project's credentials.
+ */
+
+/** What a credential is shown as instead. */
+export const STUDIO_SESSION = '[studio-session]'
+export const APP_LAUNCH_TOKEN = '[app-launch-token]'
+export const ADDRESS_CREDENTIAL = '[credential]'
+
+const NAMED = ['access_token', 'id_token', 'refresh_token', 'code', 'session', 'session_token', 'handoff', 'auth', 'key', 'api_key'] as const
+
+/** A signed token's shape (`<base64url body>.<base64url signature>`), so `t` as a cache-busting timestamp (Vite's HMR) is not taken for one. */
+const SIGNED = /^[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}$/
+
+/** A loopback address: where the project's own pages live. */
+function local(url: URL): boolean {
+  const h = url.hostname
+  return h === 'localhost' || h === '127.0.0.1' || h === '[::1]' || h.endsWith('.localhost')
+}
+
+/** The credentials an address carries, each with what it is shown as instead; none for an address elsewhere. */
+export function credentialsIn(address: string): Array<{ secret: string; label: string }> {
+  let url: URL
+  try {
+    url = new URL(address)
+  } catch {
+    return []
+  }
+  if (!local(url)) return []
+  const out: Array<{ secret: string; label: string }> = []
+  const lists = [url.searchParams]
+  if (url.hash.length > 1) lists.push(new URLSearchParams(url.hash.slice(1)))
+  for (const params of lists) {
+    const token = params.get('token')
+    if (token) out.push({ secret: token, label: STUDIO_SESSION })
+    const launch = params.get('t')
+    if (launch && SIGNED.test(launch)) out.push({ secret: launch, label: APP_LAUNCH_TOKEN })
+    for (const name of NAMED) {
+      const value = params.get(name)
+      if (value) out.push({ secret: value, label: ADDRESS_CREDENTIAL })
+    }
+  }
+  // Too short to be a secret, and too likely to match ordinary words.
+  return out.filter((c) => c.secret.length >= 8)
+}
+
+/** Text with each secret blanked out, as typed and as an address encodes it. */
+export function redactWith(text: string, secrets: ReadonlyMap<string, string>): string {
+  let out = text
+  for (const [secret, label] of secrets) out = out.split(secret).join(label).split(encodeURIComponent(secret)).join(label)
+  return out
+}
+
+/** Every string in a value with the secrets blanked out. */
+export function redactDeep<T>(value: T, secrets: ReadonlyMap<string, string>): T {
+  if (!secrets.size) return value
+  const walk = (v: unknown): unknown => {
+    if (typeof v === 'string') return redactWith(v, secrets)
+    if (Array.isArray(v)) return v.map(walk)
+    if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v as Record<string, unknown>).map(([k, x]) => [k, walk(x)]))
+    return v
+  }
+  return walk(value) as T
+}