rnxsim 0.1.313 → 0.1.314

package/cli/commands/inspect/shared.ts

@@ -0,0 +1,353 @@
+// 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,
+  isShellCommandUnavailable,
+  readyProbeHasContent,
+  READY_NODE_STABLE_MS,
+  WAIT_READY_PROBE,
+  type ReadyProbe,
+} from './core'
+import type { SootSimScreenTransitionWaitResult } from '@sootsim/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 } = {},
+) {
+  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
+}
+
+// drives the post-reload wait with short bridge-side probes. used by
+// `sootsim reload` (both the in-place hot-remount and the full-page reload
+// paths). primary ready signal is window.__sootsimExternalAppReady, set by
+// shell-events-bridge on the `sootsim:externalAppReady` event, plus visible
+// inspectable content (or a larger non-placeholder tree) and a brief stable
+// node count. a single long in-page evaluate can hold a stale shell-owned tree
+// snapshot until it returns; separate probes let the host process pending
+// shellTreeUpdate traffic between reads. bails early if the console picks up
+// errors after a grace period with the flag still unset — fatal bundle/eval
+// failures pile up errors fast and never emit ready, so waiting the full
+// budget just wastes wall time. falls back to the same content gate on timeout
+// so apps that never wire up the shell-events bridge don't hard-fail reload.
+export async function pollForReloadReady(
+  bridge: WsBridge,
+  opts: {
+    timeoutMs?: number
+    errorGraceMs?: number
+    pollIntervalMs?: number
+  } = {},
+): Promise<ReloadReadyResult> {
+  const timeoutMs = opts.timeoutMs ?? 10000
+  const errorGraceMs = opts.errorGraceMs ?? 3000
+  const pollIntervalMs = opts.pollIntervalMs ?? 200
+  const start = Date.now()
+  const deadline = start + timeoutMs
+  let lastNodes = -1
+  let nodeStableSince = start
+  let lastExternalReady: unknown = null
+  let lastExternalErrored = false
+  let last: ReloadReadyResult = {
+    ready: false,
+    source: 'timeout',
+    elapsedMs: 0,
+    nodes: 0,
+    targets: 0,
+    liveFrameActive: false,
+    liveFrameChannels: 0,
+    liveFramePublishes: 0,
+    flag: undefined,
+    loadingText: '',
+    externalReady: null,
+    externalStatus: '',
+    externalError: '',
+    errors: 0,
+  }
+
+  while (Date.now() < deadline) {
+    try {
+      const probe = (await bridge.send({
+        type: 'evaluate',
+        code: WAIT_READY_PROBE,
+      })) as Partial<ReadyProbe> | null
+      const elapsedMs = Date.now() - start
+      const nodes = Number(probe?.nodes) || 0
+      const targets = Number(probe?.targets) || 0
+      const liveFrameActive = probe?.liveFrameActive === true
+      const liveFrameChannels = Number(probe?.liveFrameChannels) || 0
+      const liveFramePublishes = Number(probe?.liveFramePublishes) || 0
+      const errors = Number(probe?.errors) || 0
+      const readyFlag = probe?.flag === true
+      const externalReady = probe?.externalReady
+      const loadingText =
+        typeof probe?.loadingText === 'string' ? probe.loadingText.trim() : ''
+      const externalStatus =
+        typeof probe?.externalStatus === 'string' ? probe.externalStatus.trim() : ''
+      const externalError =
+        typeof probe?.externalError === 'string' ? probe.externalError.trim() : ''
+      const externalErrored =
+        typeof probe?.externalError === 'string' && externalError.length > 0
+      lastExternalReady = externalReady
+      lastExternalErrored = externalErrored
+      if (nodes !== lastNodes) {
+        lastNodes = nodes
+        nodeStableSince = elapsedMs
+      }
+      last = {
+        ready: false,
+        source: 'timeout',
+        elapsedMs,
+        nodes,
+        targets,
+        liveFrameActive,
+        liveFrameChannels,
+        liveFramePublishes,
+        flag: probe?.flag,
+        loadingText,
+        externalReady: typeof externalReady === 'boolean' ? externalReady : null,
+        externalStatus,
+        externalError,
+        errors,
+      }
+      if (
+        readyFlag &&
+        externalReady !== false &&
+        !externalErrored &&
+        !loadingText &&
+        readyProbeHasContent({ liveFrameActive, nodes, targets })
+      ) {
+        if (elapsedMs - nodeStableSince >= READY_NODE_STABLE_MS) {
+          return { ...last, ready: true, source: 'flag' }
+        }
+      }
+      if (elapsedMs >= errorGraceMs && errors > 0 && !readyFlag) {
+        return { ...last, ready: false, source: 'error-bail' }
+      }
+    } catch {
+      // transient bridge disconnect during full-page reload — keep polling.
+    }
+    await sleep(pollIntervalMs)
+  }
+
+  if (
+    lastExternalReady !== false &&
+    !lastExternalErrored &&
+    !last.loadingText &&
+    readyProbeHasContent(last)
+  ) {
+    return { ...last, ready: true, source: 'nodes-fallback' }
+  }
+  return { ...last, ready: false, source: 'timeout', elapsedMs: Date.now() - start }
+}

package/cli/commands/inspect/sleep.ts

@@ -0,0 +1,14 @@
+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]'))
+    process.exit(1)
+  }
+  await sleep(seconds * 1000)
+  console.log(`  slept ${seconds}s`)
+}

package/cli/commands/inspect/tree.ts

@@ -0,0 +1,32 @@
+// `sootsim get tree` — raw node tree dump, default depth 5.
+//
+// goes through the merged test bridge (shell + tenant) rather than the raw
+// tree message, which only walks the tenant root.
+
+import { inspectTree } 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: structured nested rects ({ type, testID?, text?, x, y, w, h,
+  // bg?, fg?, br?, children? }) in absolute device coords — for layout
+  // tooling that needs real geometry, not the rendered text dump. deeper
+  // default depth because geometry consumers want the whole tree.
+  const boxes = args.includes('--boxes')
+  const depth = positional[1] ? Number(positional[1]) : boxes ? 50 : 5
+  const { tree } = await inspectTree(
+    bridge,
+    depth,
+    boxes ? { format: 'boxes' } : undefined,
+  )
+  if (wantsJson(args)) {
+    printJson({ depth, tree: tree ?? null })
+    return
+  }
+  console.log(typeof tree === 'string' ? tree : JSON.stringify(tree, null, 2))
+}

package/cli/commands/inspect/url.ts

@@ -0,0 +1,17 @@
+// `sootsim 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,210 @@
+// sootsim wait event — block until a semantic timeline event of the
+// given kind appears, or timeout.
+//
+// usage:
+//   sootsim wait event <kind> [--max-ms 5000] [--since now|cursor]
+//   sootsim wait event fetch [--filter <substring>]
+//   sootsim 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 type { WsBridge } from '../../ws-bridge'
+import type {
+  SootSimTimelineEvent,
+  SootSimTimelineQuery,
+  SootSimTimelineQueryResult,
+} from '@sootsim/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:
+  //   sootsim wait event <kind>  →  ['event', '<kind>']
+  // so positional[1] is the kind.
+  const kind = positional[1]
+  if (!kind) {
+    console.error(
+      inspectUsage(
+        'wait event',
+        '<kind> [--max-ms 5000] [--filter <substring>] [--equals <exact>] [--since now|cursor]',
+      ),
+    )
+    process.exit(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'}`,
+      )
+      process.exit(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})` : ''}`,
+    )
+  }
+  process.exit(1)
+}

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

@@ -0,0 +1,24 @@
+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)`)
+    process.exit(1)
+  }
+}