peachsim 0.1.527

package/cli/drivers/playwright.ts

@@ -0,0 +1,209 @@
+// playwright driver — launches Playwright's Google Chrome for Testing via the
+// `playwright` package. availability depends on whether the package is
+// resolvable from the current working directory OR from the CLI's own
+// install tree (repo-local install is typical; the latter covers a global
+// CLI invoked from a directory with no node_modules).
+//
+// the browser runs in a *detached* child process — this CLI re-invoked as
+// its own `__internal playwright-host` (see cli/internal-child.ts) — rather
+// than in this CLI process. that is load-bearing: `rnx open` returns the
+// moment the sim connects, and playwright tears its browser down when the
+// launching process exits. an in-process launch would mean the sim vanished
+// the instant `open` finished. the detached host keeps the test browser alive
+// until the sim's page closes (e.g. via `rnx close`).
+
+import { spawn } from 'child_process'
+import { closeSync, mkdtempSync, openSync, readFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { playwrightHostLogName } from '../../src/playwright-host-log'
+import { ensureProfile, playwrightProfileUserDataDir } from '../../src/profiles'
+import { RNX_INTERNAL_CHILDREN, RNX_INTERNAL_COMMAND } from '../internal-child'
+import { getProcessComm } from '../parent-pid'
+import { rnxSelfInvocation } from '../self-invocation'
+import { ensurePlaywrightBrowser, resolvePlaywright } from './playwright-provisioning'
+import type {
+  Driver,
+  DriverAvailability,
+  DriverLaunchOptions,
+  DriverLaunchResult,
+} from './types'
+
+function probe(): DriverAvailability {
+  const resolved = resolvePlaywright()
+  if (!resolved) {
+    return {
+      available: false,
+      reason: 'playwright not installed in the current workspace',
+    }
+  }
+  return {
+    available: true,
+    reason: null,
+    detail: `resolved via ${resolved.spec}@${resolved.version}`,
+  }
+}
+
+// when a headed launch fails on a Linux box with no display, chrome's own
+// error ("Missing X server", "cannot open display") tells the user *what*
+// is wrong but not *what to do*. surface the actionable flag.
+function headlessHintForLinuxFailure(
+  opts: DriverLaunchOptions,
+  detail: string,
+): string | null {
+  if (process.platform !== 'linux') return null
+  if (opts.headless) return null
+  if (process.env.DISPLAY || process.env.WAYLAND_DISPLAY) return null
+  if (!/missing x server|cannot open display|x server|x11/i.test(detail)) {
+    return null
+  }
+  return '  hint: linux without DISPLAY/WAYLAND_DISPLAY — rerun without --headed (or add --headless) to run playwright headless.'
+}
+
+// resolve the Chrome user-data dir for a profiled launch. a non-empty
+// return means the host should use a persistent context; '' means a plain
+// (in-memory) browser launch.
+function resolveUserDataDir(opts: DriverLaunchOptions): string {
+  if (opts.profileId) {
+    return playwrightProfileUserDataDir(ensureProfile(opts.profileId).id)
+  }
+  if (opts.ephemeralProfile) {
+    return mkdtempSync(join(tmpdir(), 'rnx-playwright-profile-'))
+  }
+  return ''
+}
+
+async function launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult> {
+  const resolved = resolvePlaywright()
+  if (!resolved) {
+    return {
+      launched: false,
+      message: 'playwright not installed — run `bun add -D playwright` first',
+    }
+  }
+  if (!opts.url) {
+    return { launched: false, message: 'playwright driver requires a target url' }
+  }
+  const ownerPid = opts.ownerPid
+  if (ownerPid === undefined || !Number.isInteger(ownerPid) || ownerPid <= 1) {
+    return {
+      launched: false,
+      message: 'playwright driver requires a valid owning session process',
+    }
+  }
+
+  // keep browser discovery, installation, and the detached host on one exact
+  // cache contract even if another caller mutates process.env during launch.
+  const playwrightEnv = { ...process.env }
+  const provisioning = ensurePlaywrightBrowser(resolved, playwrightEnv)
+  if (!provisioning.ok) {
+    return {
+      launched: false,
+      message: `playwright browser provisioning failed: ${provisioning.message}`,
+    }
+  }
+
+  const errLog = join(tmpdir(), playwrightHostLogName(Date.now(), process.pid))
+  const connectAckFile = `${errLog}.connected`
+  const errFd = openSync(errLog, 'a')
+  try {
+    // spawn the browser host detached so Chrome outlives `rnx
+    // open`. stdout is dropped; stderr is captured to errLog so an early
+    // crash (bad profile dir, missing browser binary) produces a real
+    // message instead of a silent "timed out waiting for sim".
+    // resolve the owning session's pid *before* we detach — after the spawn,
+    // the host's own ancestry is just launchd. the host polls this pid and
+    // tears Chrome down when the session that launched it exits.
+    const self = rnxSelfInvocation()
+    const child = spawn(
+      self.executable,
+      [...self.prefixArgs, RNX_INTERNAL_COMMAND, RNX_INTERNAL_CHILDREN.playwrightHost],
+      {
+        detached: true,
+        stdio: ['ignore', 'ignore', errFd],
+        env: {
+          ...playwrightEnv,
+          SOOTSIM_PW_MODULE: resolved.modulePath,
+          SOOTSIM_PW_URL: opts.url,
+          SOOTSIM_PW_BRIDGE_PORT: opts.bridgePort ? String(opts.bridgePort) : '',
+          SOOTSIM_PW_HEADLESS: (opts.headless ?? true) ? '1' : '0',
+          SOOTSIM_PW_USERDATADIR: resolveUserDataDir(opts),
+          SOOTSIM_PW_CDP_PORT: opts.cdpPort ? String(opts.cdpPort) : '',
+          // when the caller passed no viewport, leave the inherited
+          // SOOTSIM_PW_VIEWPORT (from playwrightEnv) alone instead of
+          // clobbering it with '' — the driver reads it as its own default.
+          ...(opts.viewport
+            ? { SOOTSIM_PW_VIEWPORT: `${opts.viewport.width}x${opts.viewport.height}` }
+            : {}),
+          SOOTSIM_PW_CONNECTED_ACK_FILE: connectAckFile,
+          SOOTSIM_PW_CONNECT_TIMEOUT_MS: String(opts.connectTimeoutMs ?? 120_000),
+          SOOTSIM_PW_OWNER_PID: String(ownerPid),
+        },
+      },
+    )
+    child.unref()
+
+    // give the host a short window to fail fast (resolve errors, browser
+    // binary missing). if it is still alive after that, the sim is on its
+    // way and the caller's own `waitForSimMatch` takes over.
+    const earlyExit = await new Promise<number | null>((resolve) => {
+      const timer = setTimeout(() => resolve(null), 4000)
+      child.once('exit', (code) => {
+        clearTimeout(timer)
+        resolve(code ?? 0)
+      })
+    })
+    if (earlyExit !== null) {
+      // ANY exit inside the 4s startup window is a failure: a healthy host
+      // stays alive until the sim disconnects (much longer than 4s). a code-0
+      // early exit can happen when the inline script's top-level catch fires
+      // before the launch even reaches a thrown error path, or when chromium
+      // is killed externally — both still mean "no sim is coming". emit the
+      // host's FULL stderr — its first line is the error message, and the
+      // prior `slice(-3)` kept only trailing stack frames, dropping the
+      // message and making CI failures undiagnosable. leave errLog on disk
+      // (path included) so it can be inspected after the fact.
+      const detail = readFileSync(errLog, 'utf8').trim()
+      const hint = headlessHintForLinuxFailure(opts, detail)
+      return {
+        launched: false,
+        message: `playwright host exited early (code ${earlyExit}) — host log ${errLog}${
+          detail ? `:\n${detail}` : ''
+        }${hint ? `\n${hint}` : ''}`,
+      }
+    }
+    // name the lifetime tie: the host watchdog closes chrome ~5s after the
+    // owning session pid exits, which surprises one-shot/detached shells
+    // (their topmost non-init ancestor is the shell itself, so the sim dies
+    // the moment the command finishes).
+    const ownerComm = getProcessComm(ownerPid)
+    const ownerNote = ` — browser closes when pid ${ownerPid}${ownerComm ? ` (${ownerComm})` : ''} exits`
+    return {
+      launched: true,
+      message: `playwright chrome launched → ${opts.url}${ownerNote}`,
+      pid: child.pid,
+      target: resolved.spec,
+      attachUrl: opts.url,
+      connectAckFile,
+      diagnosticLogPath: errLog,
+    }
+  } catch (err) {
+    return {
+      launched: false,
+      message: `playwright launch failed: ${err instanceof Error ? err.message : String(err)}`,
+    }
+  } finally {
+    // parent's copy of the fd; the detached host keeps its own inherited
+    // dup, so closing here does not cut off the child's stderr.
+    closeSync(errFd)
+  }
+}
+
+export const playwrightDriver: Driver = {
+  id: 'playwright',
+  name: 'playwright',
+  description: 'programmatic chromium via the playwright package — headless default',
+  kind: 'automation',
+  availability: probe,
+  launch,
+}

package/cli/drivers/registry.ts

@@ -0,0 +1,65 @@
+// driver registry — hardcoded list of known drivers plus lookup helpers.
+// kept intentionally flat: no DI, no plugin discovery, no lazy imports. both
+// built-in drivers load unconditionally because their module bodies are cheap
+// (no I/O, no side effects).
+
+import { electronDriver } from './electron'
+import { playwrightDriver } from './playwright'
+import type { Driver, DriverId } from './types'
+
+export const ALL_DRIVERS: readonly Driver[] = [electronDriver, playwrightDriver]
+
+export function getAllDrivers(): readonly Driver[] {
+  return ALL_DRIVERS
+}
+
+export function getDriver(id: DriverId): Driver | null {
+  return ALL_DRIVERS.find((d) => d.id === id) ?? null
+}
+
+// returns the first driver in preference order that reports availability.
+// used by launch sites that want "pick whatever works" behavior when the
+// user didn't pass an explicit --driver flag. if `forcedId` is given, that
+// driver is returned even if unavailable so the caller can surface a
+// specific error message rather than silently falling back.
+export function resolveDriver(
+  forcedId: string | null | undefined,
+  preference: readonly DriverId[],
+): Driver | null {
+  if (forcedId) {
+    const match = ALL_DRIVERS.find((d) => d.id === forcedId)
+    return match ?? null
+  }
+  for (const id of preference) {
+    const driver = ALL_DRIVERS.find((d) => d.id === id)
+    if (driver && driver.availability().available) return driver
+  }
+  return null
+}
+
+// utility for the `rnx list --drivers` view. returns a rich row per
+// driver with availability + kind + description, suitable for a table.
+export interface DriverListRow {
+  id: DriverId
+  name: string
+  kind: Driver['kind']
+  description: string
+  available: boolean
+  reason: string | null
+  detail: string | null
+}
+
+export function buildDriverListRows(): DriverListRow[] {
+  return ALL_DRIVERS.map((d) => {
+    const probe = d.availability()
+    return {
+      id: d.id,
+      name: d.name,
+      kind: d.kind,
+      description: d.description,
+      available: probe.available,
+      reason: probe.reason,
+      detail: probe.detail ?? null,
+    }
+  })
+}

package/cli/drivers/types.ts

@@ -0,0 +1,102 @@
+// driver / runner abstraction for rnx. browser sims run in an isolated
+// playwright-owned profile. electron remains the native desktop surface.
+
+export type DriverId = 'electron' | 'playwright'
+
+// broad category for grouping / filtering. "native" is the electron host;
+// "automation" is the isolated playwright browser.
+export type DriverKind = 'native' | 'automation'
+
+export interface DriverAvailability {
+  // true when the driver can attempt a launch on this machine. a driver is
+  // allowed to be available but still fail at runtime (network issues,
+  // permission denied, ...). false when there's a hard precondition missing
+  // (binary not installed, package not resolvable).
+  available: boolean
+  // short free-text explaining why a driver is unavailable. null when
+  // `available` is true, or when no reason is known.
+  reason: string | null
+  // optional human-readable detail shown in verbose listings — e.g. the
+  // resolved binary path, version string, or install location.
+  detail?: string
+}
+
+export interface DriverLaunchOptions {
+  // shell URL to load in the launched process. optional because the electron
+  // driver can launch the companion app with
+  // no URL (it picks its last window). other drivers return launched:false
+  // with a helpful message when url is missing.
+  url?: string
+  // run in headless mode where the driver supports it. ignored by electron.
+  headless?: boolean
+  // initial device model seed forwarded to the rnx shell. the electron
+  // driver forwards it via argv (--device=<model>); browser drivers receive
+  // it already stamped on the URL (?device=<model>) by runOpenCommand.
+  device?: string
+  // page viewport for browser-based drivers. runOpenCommand sizes this from
+  // the device profile (device pt size + frame chrome) so the sim isn't
+  // letterboxed inside playwright's 1280x720 default.
+  viewport?: { width: number; height: number }
+  // let the caller override the port used in availability / attach
+  // heuristics. most drivers don't need this.
+  port?: number
+  // when true, the launch is detached from the parent process and the
+  // CLI returns immediately. default true.
+  detached?: boolean
+  // named persistent storage profile. honored by drivers that own their
+  // browser context (electron, playwright). plain browser tabs reject it.
+  profileId?: string
+  // unnamed temporary storage. honored by electron/playwright.
+  ephemeralProfile?: boolean
+  // stable pid for the session that owns a CLI-opened host. electron closes
+  // only that session's windows when the owner exits; playwright requires it
+  // so a detached browser can never outlive its session. omitted only for the
+  // persistent `rnx desktop` app lifecycle.
+  ownerPid?: number
+  // expose Chrome's remote-debugging endpoint on this port so a
+  // bridge-driven sim can also be cpu-profiled. only the playwright driver
+  // honors it (launches Chromium with --remote-debugging-port).
+  cdpPort?: number
+  // maximum time the detached host should wait for the launched sim to
+  // register with the bridge before it tears itself down.
+  connectTimeoutMs?: number
+  // the rnx WS bridge port the launched sim page should register with,
+  // injected as window.__sootsimBridgePort. load-bearing when the dev bridge
+  // drifted off the shell-port-implied default (e.g. :7668 taken at the shell's
+  // boot -> bridge on :7669 while the shell kept :5173): the page's own
+  // shell-port heuristic would compute the stale :7668 and never connect.
+  bridgePort?: number
+}
+
+export interface DriverLaunchResult {
+  // true when the process was successfully spawned.
+  launched: boolean
+  // free-text describing what happened, used for CLI output and skill docs.
+  message: string
+  // optional handle details — currently free-shaped so each driver can
+  // expose what makes sense for its environment. pid for spawned processes,
+  // `target` for an install path, `attachUrl` for automation drivers.
+  pid?: number
+  target?: string
+  attachUrl?: string
+  connectAckFile?: string
+  diagnosticLogPath?: string
+}
+
+export interface Driver {
+  id: DriverId
+  // short human name shown in `rnx list --drivers`.
+  name: string
+  // one-line description. keep under 80 chars so the list command reads
+  // nicely at default terminal width.
+  description: string
+  kind: DriverKind
+  // probe the host environment for this driver. cheap and synchronous —
+  // anything expensive belongs in `launch`.
+  availability(): DriverAvailability
+  // start the driver pointed at `opts.url`. may be async because some
+  // drivers (electron, playwright) do real I/O. must never throw on a
+  // benign "not installed" condition — return { launched: false } with a
+  // helpful message instead.
+  launch(opts: DriverLaunchOptions): Promise<DriverLaunchResult>
+}

package/cli/flow-export.ts

@@ -0,0 +1,55 @@
+// turning a recorded flow draft into a maestro-compatible YAML file.
+//
+// this is separate from flow-session.ts, the draft store, because the two have
+// different reach. every `do` verb writes a candidate into the store, so the
+// store has to load wherever the CLI's runtime commands load, including inside
+// a box shell running in workerd, where the `yaml` package does not load at
+// all. YAML formatting and writing the file are the export step, and only
+// `rnx flow` and `rnx maestro` ever reach it.
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import yaml from 'yaml'
+import { validateFlowSteps } from './flow-file'
+import { finalizeFlowSession, readFlowSession } from './flow-session'
+
+export function exportFlowSession(outputPath?: string) {
+  const state = readFlowSession()
+  if (!state) return { active: false as const }
+
+  const yamlText = `${yaml.stringify(state.steps).trimEnd()}\n`
+  const issues = validateFlowSteps(state.steps)
+  if (issues.length > 0) {
+    return {
+      active: true as const,
+      valid: false as const,
+      issues,
+      yaml: yamlText,
+      stepCount: state.steps.length,
+      outputPath: null,
+    }
+  }
+
+  let resolvedOutputPath: string | null = null
+  if (outputPath) {
+    resolvedOutputPath = resolve(outputPath)
+    mkdirSync(dirname(resolvedOutputPath), { recursive: true })
+    writeFileSync(resolvedOutputPath, yamlText)
+  }
+
+  return {
+    active: true as const,
+    valid: true as const,
+    issues: [],
+    yaml: yamlText,
+    stepCount: state.steps.length,
+    outputPath: resolvedOutputPath,
+  }
+}
+
+export function endFlowSession(outputPath?: string) {
+  const result = exportFlowSession(outputPath)
+  if (!result.active) return result
+  finalizeFlowSession()
+  return result
+}

package/cli/flow-file.ts

@@ -0,0 +1,142 @@
+import * as fs from 'fs'
+import yaml from 'yaml'
+
+export interface FlowFrontmatter {
+  // raw `rnx open` target: port, dev-server URL, bundle URL, or shell URL
+  app?: string | number
+  device?: string
+  // pin the sim color scheme for this flow run (screenshot baselines are
+  // theme-sensitive; a dark capture can never match a light baseline)
+  theme?: 'light' | 'dark'
+  electron?: boolean
+  // maestro-compatible: appId is accepted but not used by rnx (ios bundle id)
+  appId?: string
+  // maestro-compatible: flow-level env vars, defined into the flow's JS
+  // context before the first step runs
+  env?: Record<string, string>
+  // maestro-compatible: workspace tag filtering (config.yml includeTags/excludeTags)
+  tags?: string[]
+}
+
+// parse flow file. accepts three shapes:
+//   1. plain yaml array of steps (no frontmatter)
+//   2. rnx style: ---\n<fm>\n---\n<steps>
+//   3. maestro style: <fm>\n---\n<steps>   (multi-doc yaml, fm first)
+// maestro compat matters because real users have real .maestro/*.yaml files
+// and shouldn't have to rewrite them to drive rnx.
+//
+// `${...}` templates are NOT resolved here — interpolation happens per-step
+// at execution time in the flow runner's JS context (matching maestro), so
+// values produced mid-flow (runScript output.*, copyTextFrom) resolve in
+// later steps and a missing variable fails loudly at the exact step.
+export function parseFlowFile(content: string): {
+  frontmatter: FlowFrontmatter
+  steps: any[]
+} {
+  let frontmatter: FlowFrontmatter = {}
+  let body = content
+  const normalizeSteps = (steps: unknown): any[] => {
+    return Array.isArray(steps) ? steps : []
+  }
+
+  // shape 2: leading ---\n<fm>\n---\n<body>
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?/)
+  if (fmMatch) {
+    try {
+      frontmatter = (yaml.parse(fmMatch[1]) as FlowFrontmatter) ?? {}
+    } catch (e) {
+      console.warn(`  warn: could not parse frontmatter: ${(e as Error).message}`)
+    }
+    body = content.slice(fmMatch[0].length)
+    const steps = yaml.parse(body)
+    return { frontmatter, steps: normalizeSteps(steps) }
+  }
+
+  // shape 3: maestro multi-doc (fm-first, then `---`, then steps)
+  // detect cheaply: a `---` separator on its own line not at position 0
+  if (/\n---\s*\n/.test(content)) {
+    try {
+      const docs = yaml.parseAllDocuments(content)
+      if (docs.length >= 2) {
+        const fm = docs[0].toJS() as FlowFrontmatter | null
+        const st = docs[docs.length - 1].toJS()
+        return {
+          frontmatter: fm && typeof fm === 'object' ? fm : {},
+          steps: normalizeSteps(st),
+        }
+      }
+    } catch (e) {
+      console.warn(`  warn: could not parse multi-doc flow: ${(e as Error).message}`)
+    }
+  }
+
+  // shape 1: plain steps array
+  const steps = yaml.parse(body)
+  return { frontmatter, steps: normalizeSteps(steps) }
+}
+
+const INTERACTION_KEYS = new Set([
+  'tapOn',
+  'inputText',
+  'pressKey',
+  'dispatchKey',
+  'hideKeyboard',
+  'swipe',
+  'pinch',
+  'scroll',
+  'scrollUntilVisible',
+])
+
+export function validateFlowSteps(steps: any[]): string[] {
+  const issues: string[] = []
+  if (!Array.isArray(steps) || steps.length === 0) {
+    issues.push('flow body must be a non-empty YAML array of steps')
+    return issues
+  }
+
+  let interactions = 0
+  for (const step of steps) {
+    if (step && typeof step === 'object') {
+      const keys = Object.keys(step)
+      if (keys.some((key) => INTERACTION_KEYS.has(key))) interactions += 1
+    } else if (typeof step === 'string' && INTERACTION_KEYS.has(step)) {
+      interactions += 1
+    }
+  }
+
+  if (interactions === 0) {
+    issues.push(
+      'no interaction steps found (expected at least one tapOn / inputText / pressKey / swipe / scroll)',
+    )
+  }
+
+  return issues
+}
+
+// structural-only validator used by CI runners before uploading the flow
+// artifact. we only check: file exists, parseable yaml, has at least one
+// real interaction step. playback validation is a separate concern handled
+// by `rnx maestro end --validate` during the authoring session.
+export function validateFlowFile(flowPath: string): string[] {
+  if (!fs.existsSync(flowPath)) {
+    return [`file not found: ${flowPath}`]
+  }
+
+  let content: string
+  try {
+    content = fs.readFileSync(flowPath, 'utf8')
+  } catch (e) {
+    return [`cannot read file: ${(e as Error).message}`]
+  }
+
+  if (content.trim().length === 0) {
+    return ['file is empty']
+  }
+
+  try {
+    const parsed = parseFlowFile(content)
+    return validateFlowSteps(parsed.steps)
+  } catch (e) {
+    return [`yaml parse error: ${(e as Error).message}`]
+  }
+}