peachsim 0.1.527

package/cli/commands/inspect/shared.ts

@@ -0,0 +1,259 @@
+// shared helpers for inspect subcommands.
+//
+// pulled out of the monolithic inspect.ts so each subcommand can live in its
+// own file without reaching back into a 4000-line switch. everything here is
+// call-agnostic: just bridge-facing helpers that any subcommand can use.
+
+import {
+  callInBridge,
+  callInBridgeWrite,
+  createBridge,
+  type ParsedBridgeCliArgs,
+  type WsBridge,
+} from '../../ws-bridge'
+import { getShellState, inspectWaitReady, isShellCommandUnavailable } from './core'
+import type { SootSimScreenTransitionWaitResult } from '@rnx/globals'
+
+// shell-state helpers live in the transport-agnostic kernel module so the CLI
+// and the in-browser agent share one implementation. re-exported here so
+// existing subcommand imports (`./shared`) keep working.
+export { getShellState, isShellCommandUnavailable }
+
+export const SCREEN_TRANSITION_PREFLIGHT = {
+  timeoutMs: 1800,
+  settleMs: 48,
+  startWindowMs: 64,
+} as const
+
+export function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+// true when the caller passed --json. read verbs use this to route their
+// payload to stdout-as-json and send everything else (headers, hints,
+// warnings) to stderr so `jq` on stdout never sees framing noise.
+export function wantsJson(args: string[]): boolean {
+  return args.includes('--json')
+}
+
+// emit a stable JSON document on stdout. no trailing prose, no ANSI,
+// no colors. the 2-space indent matches the rest of the CLI and is
+// cheap enough that pretty-printing by default is fine for bisect
+// scripts — consumers who care pipe through `jq -c`.
+export function printJson(payload: unknown): void {
+  process.stdout.write(`${JSON.stringify(payload ?? null, null, 2)}\n`)
+}
+
+// warnings, hints, "screen transition still active" messages — anything
+// that isn't the payload. always goes to stderr so stdout stays parseable.
+export function printWarn(msg: string): void {
+  process.stderr.write(`${msg}\n`)
+}
+
+// 24-hour wall-clock + relative offset for log/error/network timestamps.
+// agents reading these care most about "is this new or stale" — append
+// "+<n>s" for things younger than 60s. older entries keep the relative
+// stamp in m/h/d so it's still scannable without diffing wall-clock times.
+//
+// returns "HH:MM:SS +Xs" where wall clock is locale-independent 24-hour.
+// callers can wrap it in their own padding/dim ANSI.
+export function formatLogTimestamp(ts: number, nowMs: number = Date.now()): string {
+  const d = new Date(ts)
+  const wall = `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`
+  const deltaMs = nowMs - ts
+  if (deltaMs < 0) return wall
+  const sec = Math.round(deltaMs / 1000)
+  if (sec < 60) return `${wall} +${sec}s`
+  if (sec < 3600) return `${wall} +${Math.round(sec / 60)}m`
+  if (sec < 86400) return `${wall} +${Math.round(sec / 3600)}h`
+  return `${wall} +${Math.round(sec / 86400)}d`
+}
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n)
+}
+
+export async function callTestBridge<T = unknown>(
+  bridge: WsBridge,
+  method: string,
+  ...args: unknown[]
+): Promise<T> {
+  return callInBridge<T>(bridge, `__sootsimTest.${method}`, ...args)
+}
+
+export async function callShellCommand<T = unknown>(
+  bridge: WsBridge,
+  method: 'launchApp' | 'goHome' | 'openSwitcher' | 'openSwitcherCard',
+  ...args: unknown[]
+): Promise<T> {
+  return callInBridgeWrite<T>(bridge, `SootSim.bridges.mainShell.${method}`, ...args)
+}
+
+export async function maybeWaitForStartedScreenTransitions(
+  bridge: WsBridge,
+  opts: { verbose?: boolean } = {},
+) {
+  if (bridge.plane === 'cloud') return
+  try {
+    const result = await callTestBridge<SootSimScreenTransitionWaitResult>(
+      bridge,
+      'waitForScreenTransitions',
+      SCREEN_TRANSITION_PREFLIGHT,
+    )
+    if (!opts.verbose || !result?.started) return
+    if (result.timedOut) {
+      console.log(
+        `  screen transition still active after ${result.waitedMs}ms; continuing`,
+      )
+      return
+    }
+    if (result.waitedMs > 0) {
+      console.log(`  waited ${result.waitedMs}ms for screen transition settle`)
+    }
+  } catch {
+    // best-effort preflight only — older runtimes or boot races should not
+    // block the actual command.
+  }
+}
+
+export async function callShellCommandWhenReady<T = unknown>(
+  bridge: WsBridge,
+  method: 'launchApp' | 'goHome' | 'openSwitcher' | 'openSwitcherCard',
+  readyTimeoutMs: number,
+  ...args: unknown[]
+): Promise<T> {
+  const deadline = Date.now() + Math.max(0, readyTimeoutMs)
+  while (true) {
+    try {
+      return await callShellCommand<T>(bridge, method, ...args)
+    } catch (error) {
+      if (!isShellCommandUnavailable(error) || Date.now() >= deadline) throw error
+      await sleep(50)
+    }
+  }
+}
+
+export async function waitForSimReady(
+  wsPort: number,
+  commandTimeoutMs: number,
+  simId?: string,
+  opts: {
+    attempts?: number
+    intervalMs?: number
+    minNodeCount?: number
+    simIdSource?: ParsedBridgeCliArgs['simIdSource']
+  } = {},
+) {
+  const attempts = opts.attempts ?? 30
+  const intervalMs = opts.intervalMs ?? 500
+  const minNodeCount = opts.minNodeCount ?? 10
+
+  for (let i = 0; i < attempts; i++) {
+    const bridge = createBridge(wsPort, {
+      commandTimeoutMs,
+      simId,
+      simIdSource: opts.simIdSource,
+    })
+    try {
+      const count = await bridge.send({
+        type: 'evaluate',
+        code: '(async () => (await window.__sootsimTest?.getNodeCount()) || 0)()',
+      })
+      if (typeof count === 'number' && count > minNodeCount) {
+        return { bridge, count }
+      }
+    } catch {
+      // still loading or disconnected
+    }
+    bridge.close()
+    await sleep(intervalMs)
+  }
+
+  return null
+}
+
+// waits until a bridge can evaluate a trivial expression. used by the reload
+// full-page path after window.location.reload() to re-establish a bridge
+// before handing off to pollForReloadReady. intentionally does not gate on
+// node count — that check belongs in the subsequent ready poll, which uses
+// the __sootsimExternalAppReady flag as its primary signal.
+export async function waitForBridgeConnected(
+  wsPort: number,
+  commandTimeoutMs: number,
+  simId: string | undefined,
+  opts: {
+    timeoutMs?: number
+    intervalMs?: number
+    simIdSource?: ParsedBridgeCliArgs['simIdSource']
+  } = {},
+): Promise<WsBridge | null> {
+  const timeoutMs = opts.timeoutMs ?? 8000
+  const intervalMs = opts.intervalMs ?? 250
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const bridge = createBridge(wsPort, {
+      commandTimeoutMs,
+      simId,
+      simIdSource: opts.simIdSource,
+    })
+    try {
+      await bridge.send({ type: 'evaluate', code: '1' })
+      return bridge
+    } catch {
+      bridge.close()
+    }
+    await sleep(intervalMs)
+  }
+  return null
+}
+
+export interface ReloadReadyResult {
+  ready: boolean
+  source: 'flag' | 'nodes-fallback' | 'error-bail' | 'timeout'
+  elapsedMs: number
+  nodes: number
+  targets: number
+  liveFrameActive: boolean
+  liveFrameChannels: number
+  liveFramePublishes: number
+  flag: unknown
+  loadingText: string
+  externalReady: boolean | null
+  externalStatus: string
+  externalError: string
+  errors: number
+}
+
+// post-reload readiness is the same engine-owned condition as `rnx wait ready`.
+// keeping reload on that primitive prevents another polling implementation
+// from drifting on loading text, live frames, or tree stability.
+export async function pollForReloadReady(
+  bridge: WsBridge,
+  opts: { timeoutMs?: number } = {},
+): Promise<ReloadReadyResult> {
+  const timeoutMs = opts.timeoutMs ?? 10000
+  const status = await inspectWaitReady(bridge, timeoutMs)
+  const source = status.ready
+    ? status.flag === true
+      ? 'flag'
+      : 'nodes-fallback'
+    : status.errors > 0 && status.flag !== true
+      ? 'error-bail'
+      : 'timeout'
+  return {
+    ready: status.ready,
+    source,
+    elapsedMs: status.elapsedMs,
+    nodes: status.nodes,
+    targets: status.targets,
+    liveFrameActive: status.liveFrameActive,
+    liveFrameChannels: status.liveFrameChannels,
+    liveFramePublishes: status.liveFramePublishes,
+    flag: status.flag,
+    loadingText: status.loadingText,
+    externalReady: status.externalReady,
+    externalStatus: status.externalStatus,
+    externalError: status.externalError,
+    errors: status.errors,
+  }
+}

package/cli/commands/inspect/sleep.ts

@@ -0,0 +1,15 @@
+import { rnxExit } from '../../run-rnx'
+import { sleep } from './shared'
+
+export async function runSleepSubcommand(opts: {
+  positional: string[]
+  inspectUsage: (name: string, tail: string) => string
+}): Promise<void> {
+  const seconds = opts.positional[1] ? Number(opts.positional[1]) : 0.5
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    console.error(opts.inspectUsage('sleep', '[seconds]'))
+    rnxExit(1)
+  }
+  await sleep(seconds * 1000)
+  console.log(`  slept ${seconds}s`)
+}

package/cli/commands/inspect/tree.ts

@@ -0,0 +1,23 @@
+// `rnx get tree` — pruned structured semantic tree, default depth 5.
+
+import { formatSemanticTree, inspectTree, isSimSemanticTree } from './core'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runTreeSubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+  positional: string[]
+}): Promise<void> {
+  const { bridge, args, positional } = opts
+  // --boxes keeps the deeper default expected by geometry consumers. the
+  // semantic tree is structured in both modes.
+  const boxes = args.includes('--boxes')
+  const depth = positional[1] ? Number(positional[1]) : boxes ? 50 : 5
+  const { tree } = await inspectTree(bridge, depth)
+  if (wantsJson(args)) {
+    printJson({ depth, tree: tree ?? null })
+    return
+  }
+  console.log(isSimSemanticTree(tree) ? formatSemanticTree(tree) : '')
+}

package/cli/commands/inspect/url.ts

@@ -0,0 +1,17 @@
+// `rnx get url` — prints the current page URL the bridge is attached to.
+
+import { inspectUrl } from './core'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runUrlSubcommand(
+  bridge: WsBridge,
+  opts: { args: string[] } = { args: [] },
+): Promise<void> {
+  const result = await inspectUrl(bridge)
+  if (wantsJson(opts.args)) {
+    printJson(result)
+    return
+  }
+  console.log(result.url)
+}

package/cli/commands/inspect/wait-event.ts

@@ -0,0 +1,211 @@
+// rnx wait event — block until a semantic timeline event of the
+// given kind appears, or timeout.
+//
+// usage:
+//   rnx wait event <kind> [--max-ms 5000] [--since now|cursor]
+//   rnx wait event fetch [--filter <substring>]
+//   rnx wait event screen [--equals SignInPage]
+//
+// the existing wait family is layout-driven: `wait selector` polls
+// for a testID, `wait idle` polls for rAF + animation settling,
+// `wait ready` polls for bundle paint. `wait event` is the
+// timeline-driven companion: agents that want to drive "tap → wait
+// for the BeginSignIn fetch to land → tap next" no longer need to
+// chain `do tap-text Continue` + `sleep 4` + `what-happened --kinds
+// fetch --since 4s | grep BeginSignIn`. one read returns when the
+// next event of the requested kind appears.
+//
+// the implementation polls timeline.recent() — server-side
+// subscription would be cheaper but a 200ms poll is plenty for the
+// human-paced UI events we care about and stays compatible with the
+// existing query surface.
+
+import { rnxExit } from '../../run-rnx'
+import type { WsBridge } from '../../ws-bridge'
+import type {
+  SootSimTimelineEvent,
+  SootSimTimelineQuery,
+  SootSimTimelineQueryResult,
+} from '@rnx/globals'
+
+interface WaitEventOptions {
+  bridge: WsBridge
+  args: string[]
+  positional: string[]
+  inspectUsage: (name: string, tail: string) => string
+}
+
+// every timeline event kind the cli currently knows about. matching
+// the type on `SootSimTimelineEvent['kind']` would be more strict
+// but the timeline can grow new kinds and we don't want this
+// command to refuse an unknown one — the worst case is the wait
+// just times out, which is exactly the right behaviour.
+const KNOWN_KINDS = new Set([
+  'app-launch',
+  'toast',
+  'keyboard',
+  'screen',
+  'flow-step',
+  'route',
+  'alert',
+  'actionsheet',
+  'picker',
+  'notification',
+  'fetch',
+  'console',
+  'shell',
+  'scroll',
+  'gesture',
+  'text-input',
+  'react-commit',
+  'animation',
+  'reanimated',
+])
+
+function findFlagValue(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag)
+  if (idx >= 0 && idx + 1 < args.length) return args[idx + 1]
+  return undefined
+}
+
+function eventMatches(
+  ev: SootSimTimelineEvent,
+  opts: { filter?: string; equals?: string },
+): boolean {
+  if (!opts.filter && !opts.equals) return true
+  const data = ev.data as Record<string, unknown> | null
+  // build a one-string haystack from the most-likely-relevant fields
+  // per kind. agents asking for `wait event fetch --filter BeginSignIn`
+  // expect to match the URL; `wait event screen --equals Inbox`
+  // expects to match the screen name.
+  const haystack: string[] = []
+  if (data && typeof data === 'object') {
+    for (const key of [
+      'url',
+      'displayUrl',
+      'message',
+      'name',
+      'activeName',
+      'path',
+      'pathname',
+      'title',
+      'phase',
+      'event',
+      'type',
+      'kind',
+    ]) {
+      const v = data[key]
+      if (typeof v === 'string' && v.length > 0) haystack.push(v)
+    }
+  }
+  const joined = haystack.join(' ')
+  if (opts.equals) {
+    return haystack.some((s) => s === opts.equals)
+  }
+  if (opts.filter) {
+    return joined.toLowerCase().includes(opts.filter.toLowerCase())
+  }
+  return true
+}
+
+export async function runWaitEventSubcommand(opts: WaitEventOptions): Promise<void> {
+  const { bridge, args, positional, inspectUsage } = opts
+  // positional shape after verb-prefix strip and stripBooleanFlags:
+  //   rnx wait event <kind>  →  ['event', '<kind>']
+  // so positional[1] is the kind.
+  const kind = positional[1]
+  if (!kind) {
+    console.error(
+      inspectUsage(
+        'event',
+        '<kind> [--max-ms 5000] [--filter <substring>] [--equals <exact>] [--since now|cursor]',
+      ),
+    )
+    rnxExit(1)
+  }
+  if (!KNOWN_KINDS.has(kind)) {
+    console.error(
+      `  warning: '${kind}' is not a known timeline kind — waiting anyway. known: ${[...KNOWN_KINDS].sort().join(', ')}`,
+    )
+  }
+
+  const maxMsRaw = findFlagValue(args, '--max-ms')
+  const maxMs =
+    maxMsRaw && Number.isFinite(Number(maxMsRaw)) ? Math.max(100, Number(maxMsRaw)) : 5000
+
+  const filter = findFlagValue(args, '--filter')
+  const equals = findFlagValue(args, '--equals')
+  const sinceMode = findFlagValue(args, '--since') ?? 'now'
+  const jsonOut = args.includes('--json')
+
+  // capture the start watermark so we don't match an event that
+  // happened before this command. agents calling `wait event fetch`
+  // after a tap mean "the *next* fetch", not "any fetch since the
+  // session started". `--since cursor` falls back to the
+  // what-happened cursor semantics for callers that explicitly want
+  // that.
+  const startedAt = Date.now()
+  const deadline = startedAt + maxMs
+  const pollMs = 200
+
+  let lastWatermark = startedAt
+
+  while (Date.now() < deadline) {
+    const query: SootSimTimelineQuery = {
+      kinds: [kind] as SootSimTimelineQuery['kinds'],
+      since: sinceMode === 'cursor' ? undefined : lastWatermark,
+      limit: 50,
+    }
+    const result = (await bridge.send({
+      type: 'evaluate',
+      // hand-marshal the query through evaluate — the bridge already
+      // exposes `SootSim.bridges.timeline.recent` as a sync method,
+      // but evaluate is the universally available shape and the cost
+      // of a string-baked function is negligible at 5Hz.
+      code: `(async () => {
+        const t = window.SootSim?.bridges?.timeline
+        if (!t) return { ok: false, error: 'timeline bridge missing' }
+        return { ok: true, result: await t.recent(${JSON.stringify(query)}) }
+      })()`,
+    })) as { ok: true; result: SootSimTimelineQueryResult } | { ok: false; error: string }
+    if (!result || !result.ok) {
+      console.error(
+        `  could not query timeline: ${result && 'error' in result ? result.error : 'unknown'}`,
+      )
+      rnxExit(1)
+    }
+    const evts = result.result.events ?? []
+    for (const ev of evts) {
+      if (eventMatches(ev, { filter, equals })) {
+        const elapsed = Date.now() - startedAt
+        if (jsonOut) {
+          console.log(JSON.stringify({ found: true, elapsedMs: elapsed, event: ev }))
+        } else {
+          console.log(
+            `  ${kind} event after ${elapsed}ms${filter ? ` (filter: ${filter})` : ''}${equals ? ` (equals: ${equals})` : ''}`,
+          )
+        }
+        return
+      }
+    }
+    // advance the local watermark to the high-water mark we just
+    // saw so the next poll doesn't redundantly re-scan the same
+    // events.
+    if (result.result.watermark && result.result.watermark > lastWatermark) {
+      lastWatermark = result.result.watermark
+    }
+    await new Promise((r) => setTimeout(r, pollMs))
+  }
+
+  const elapsed = Date.now() - startedAt
+  if (jsonOut) {
+    console.log(
+      JSON.stringify({ found: false, elapsedMs: elapsed, kind, filter, equals }),
+    )
+  } else {
+    console.error(
+      `  ⚠ wait event ${kind} timed out after ${elapsed}ms${filter ? ` (filter: ${filter})` : ''}${equals ? ` (equals: ${equals})` : ''}`,
+    )
+  }
+  rnxExit(1)
+}

package/cli/commands/inspect/wait-idle.ts

@@ -0,0 +1,25 @@
+import { rnxExit } from '../../run-rnx'
+import { resolveMaxMsFlag } from './core'
+import { waitForSootsimIdle } from './settling'
+import type { WsBridge } from '../../ws-bridge'
+
+// alias for `do settle` under the discoverable `wait` verb grouping.
+// layout hash stability across 3 polls; --strict also requires worker
+// animation flags to be clear.
+export async function runWaitIdleSubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+  positional: string[]
+}): Promise<void> {
+  const { bridge, args } = opts
+  const strict = args.includes('--strict')
+  const maxMs = resolveMaxMsFlag(args, 3000)
+  const { elapsed, settled } = await waitForSootsimIdle({ bridge, maxMs, strict })
+
+  if (settled) {
+    console.log(`  idle in ${elapsed}ms`)
+  } else {
+    console.error(`  ⚠ wait idle timed out after ${elapsed}ms (may still be animating)`)
+    rnxExit(1)
+  }
+}

package/cli/commands/inspect/wait-ready.ts

@@ -0,0 +1,87 @@
+import { rnxExit } from '../../run-rnx'
+import { inspectWaitReady, resolveMaxMsFlag, waitReadyReason } from './core'
+import { waitForSootsimIdle } from './settling'
+import type { WsBridge } from '../../ws-bridge'
+
+// blocks until the guest app bundle has finished loading and painted real
+// inspectable content. the persistent window flag
+// `__sootsimExternalAppReady` is necessary but not sufficient: shell-owned
+// canvas can expose a stable launch/loading tree before the app content lands.
+// the engine owns the polling loop; this handler sends one request, then
+// reports the typed result.
+export async function runWaitReadySubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+}): Promise<void> {
+  const { bridge, args } = opts
+  // default 20s because cold guest bundles (uniswap, expensify, bluesky)
+  // routinely take 10-15s to evaluate + mount.
+  const timeoutMs = resolveMaxMsFlag(args, 20000)
+
+  const {
+    ready,
+    elapsedMs,
+    nodes,
+    targets,
+    liveFrameActive,
+    liveFrameChannels,
+    flag,
+    loadingText,
+    externalReady,
+    externalStatus,
+    externalError,
+    suppressedEntryError,
+    errors,
+    bridgeError,
+  } = await inspectWaitReady(bridge, timeoutMs, {
+    ...(bridge.plane !== 'cloud'
+      ? {
+          onProgress(status) {
+            console.error(
+              `  still waiting after ${status.elapsedMs}ms — ${waitReadyReason(status)} (nodes: ${status.nodes}, targets: ${status.targets}, live surfaces: ${status.liveFrameActive ? status.liveFrameChannels : 0}, errors: ${status.errors})`,
+            )
+          },
+        }
+      : {}),
+  })
+  if (ready) {
+    if (bridge.plane === 'cloud') {
+      console.log(
+        `  ready in ${elapsedMs}ms: ${nodes} nodes, ${targets} targets${liveFrameActive ? `, ${liveFrameChannels} live surfaces` : ''}`,
+      )
+      return
+    }
+    const remainingMs = timeoutMs - elapsedMs
+    const idleBudgetMs = Math.max(100, Math.min(10_000, remainingMs))
+    const idle = await waitForSootsimIdle({
+      bridge,
+      maxMs: idleBudgetMs,
+      pollMs: 32,
+      stablePolls: 2,
+    })
+    if (!idle.settled) {
+      console.error(
+        `  ⚠ wait ready timed out after ${elapsedMs + idle.elapsed}ms — app mounted but did not settle (nodes: ${nodes}, targets: ${targets})`,
+      )
+      rnxExit(1)
+    }
+    console.log(
+      `  ready in ${elapsedMs + idle.elapsed}ms: ${nodes} nodes, ${targets} targets${liveFrameActive ? `, ${liveFrameChannels} live surfaces` : ''}`,
+    )
+    return
+  }
+  const reason = waitReadyReason({
+    externalError,
+    loadingText,
+    externalReady,
+    externalStatus,
+    flag,
+    targets,
+    suppressedEntryError,
+    bridgeError,
+  })
+  console.error(
+    `  ⚠ wait ready timed out after ${elapsedMs}ms — ${reason} (nodes: ${nodes}, targets: ${targets}, live surfaces: ${liveFrameActive ? liveFrameChannels : 0}, errors: ${errors})`,
+  )
+  rnxExit(1)
+}