peachsim 0.1.527

package/cli/flow-live-status.ts

@@ -0,0 +1,126 @@
+// flow-live-status — pushes the flow runner's live progress into the sim it
+// is driving, over the same ws bridge the steps execute on. the engine's
+// flow-run-store renders it in the shell devtools "test" tab and replies
+// with the pause intent, which the runner honors between steps.
+//
+// pushes are best-effort: an engine without the `flowStatus` handler (an
+// older shell) throws "unknown command type" once and the reporter disables
+// itself for the rest of the run. live status must never fail a test.
+
+import type { WsBridge } from './ws-bridge'
+
+export type LiveStepStatus = 'running' | 'success' | 'failure' | 'skipped'
+
+type PlanStep = { index: number; name: string; target?: string }
+
+const PAUSE_POLL_MS = 400
+
+function replyPaused(reply: unknown) {
+  if (typeof reply !== 'object' || reply == null || !('control' in reply)) return false
+  const control = reply.control
+  return (
+    typeof control === 'object' &&
+    control != null &&
+    'paused' in control &&
+    control.paused === true
+  )
+}
+
+export class FlowLiveStatusReporter {
+  private disabled = false
+  private paused = false
+  private lastSimId: string | undefined
+  private plannedSteps: PlanStep[] | null = null
+  private readonly completedSteps = new Map<
+    number,
+    { index: number; status: LiveStepStatus; durationMs?: number; error?: string }
+  >()
+  private readonly runId = `flr_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`
+
+  constructor(
+    private bridge: WsBridge,
+    private flowName: string | null,
+    private flowSource: string,
+    private getSimId?: () => string | undefined,
+  ) {}
+
+  private async send(payload: Record<string, unknown>, simId: string | undefined) {
+    const reply: unknown = await this.bridge.send({
+      type: 'flowStatus',
+      simId,
+      status: { runId: this.runId, flowName: this.flowName, ...payload },
+    })
+    this.paused = replyPaused(reply)
+  }
+
+  private async push(payload: Record<string, unknown>): Promise<void> {
+    if (this.disabled) return
+    try {
+      const simId = this.getSimId?.()
+      if (
+        simId !== this.lastSimId &&
+        this.lastSimId != null &&
+        this.plannedSteps &&
+        payload.phase !== 'plan'
+      ) {
+        await this.send(
+          {
+            phase: 'plan',
+            state: 'running',
+            steps: this.plannedSteps,
+            source: this.flowSource,
+          },
+          simId,
+        )
+        for (const step of this.completedSteps.values()) {
+          await this.send({ phase: 'step', state: 'running', step }, simId)
+        }
+      }
+      this.lastSimId = simId
+      await this.send(payload, simId)
+    } catch (error) {
+      this.disabled = true
+      console.log(
+        `[flow]   live status unavailable (${error instanceof Error ? error.message.slice(0, 120) : error}) — continuing without the devtools rail`,
+      )
+    }
+  }
+
+  async plan(steps: PlanStep[]): Promise<void> {
+    this.plannedSteps = steps.map((step) => ({ ...step }))
+    this.completedSteps.clear()
+    await this.push({ phase: 'plan', state: 'running', steps, source: this.flowSource })
+  }
+
+  async step(
+    index: number,
+    status: LiveStepStatus,
+    extra?: { durationMs?: number; error?: string },
+  ): Promise<void> {
+    const step = { index, status, ...extra }
+    await this.push({
+      phase: 'step',
+      state: 'running',
+      step,
+    })
+    this.completedSteps.set(index, step)
+  }
+
+  async end(state: 'passed' | 'failed'): Promise<void> {
+    await this.push({ phase: 'end', state })
+  }
+
+  // park while the devtools pause toggle is on. checked between top-level
+  // steps only, so a pause never interrupts a step mid-gesture.
+  async waitWhilePaused(): Promise<void> {
+    if (this.disabled) return
+    while (this.paused) {
+      console.log('[flow]   paused from devtools — waiting…')
+      while (this.paused && !this.disabled) {
+        await new Promise((resolve) => setTimeout(resolve, PAUSE_POLL_MS))
+        await this.push({ phase: 'heartbeat', state: 'paused' })
+      }
+      if (!this.disabled) console.log('[flow]   resumed')
+    }
+  }
+}

package/cli/flow-session.ts

@@ -0,0 +1,140 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join, resolve } from 'path'
+
+export type FlowDraftStep = Record<string, unknown>
+
+export interface FlowCandidate {
+  step: FlowDraftStep
+  summary: string
+  source: string
+  recordedAt: string
+}
+
+export interface FlowSessionState {
+  version: 1
+  startedAt: string
+  updatedAt: string
+  steps: FlowDraftStep[]
+  candidate: FlowCandidate | null
+}
+
+const FLOW_SESSION_VERSION = 1 as const
+
+export function getFlowSessionPath() {
+  return resolve(
+    process.env.RNX_FLOW_SESSION_PATH || join(tmpdir(), 'rnx-flow-session.json'),
+  )
+}
+
+function writeFlowSession(state: FlowSessionState) {
+  const filepath = getFlowSessionPath()
+  mkdirSync(dirname(filepath), { recursive: true })
+  writeFileSync(filepath, JSON.stringify(state, null, 2) + '\n')
+}
+
+export function readFlowSession(): FlowSessionState | null {
+  const filepath = getFlowSessionPath()
+  if (!existsSync(filepath)) return null
+
+  try {
+    const parsed = JSON.parse(readFileSync(filepath, 'utf8')) as Partial<FlowSessionState>
+    if (
+      parsed.version !== FLOW_SESSION_VERSION ||
+      !Array.isArray(parsed.steps) ||
+      typeof parsed.startedAt !== 'string' ||
+      typeof parsed.updatedAt !== 'string'
+    ) {
+      rmSync(filepath, { force: true })
+      return null
+    }
+
+    return {
+      version: FLOW_SESSION_VERSION,
+      startedAt: parsed.startedAt,
+      updatedAt: parsed.updatedAt,
+      steps: parsed.steps as FlowDraftStep[],
+      candidate: parsed.candidate ?? null,
+    }
+  } catch {
+    rmSync(filepath, { force: true })
+    return null
+  }
+}
+
+export function hasActiveFlowSession() {
+  return readFlowSession() !== null
+}
+
+export function startFlowSession() {
+  const now = new Date().toISOString()
+  const state: FlowSessionState = {
+    version: FLOW_SESSION_VERSION,
+    startedAt: now,
+    updatedAt: now,
+    steps: [],
+    candidate: null,
+  }
+  writeFlowSession(state)
+  return { path: getFlowSessionPath(), state }
+}
+
+export function clearFlowSession() {
+  rmSync(getFlowSessionPath(), { force: true })
+}
+
+export function finalizeFlowSession() {
+  clearFlowSession()
+}
+
+export function rememberFlowCandidate(input: {
+  step: FlowDraftStep
+  summary: string
+  source: string
+}) {
+  const state = readFlowSession()
+  if (!state) return { active: false as const }
+
+  // a pending candidate that was never `maestro keep`'d is silently dropped
+  // when a new action arrives — that's the "skip mistakes" model. surface
+  // the replaced action so the caller can warn (a kept action is never
+  // lost; an unkept one is).
+  const replaced = state.candidate
+  const next: FlowSessionState = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+    candidate: {
+      step: input.step,
+      summary: input.summary,
+      source: input.source,
+      recordedAt: new Date().toISOString(),
+    },
+  }
+  writeFlowSession(next)
+  return { active: true as const, candidate: next.candidate, replaced }
+}
+
+export function keepFlowCandidate() {
+  const state = readFlowSession()
+  if (!state)
+    return { active: false as const, kept: false as const, reason: 'no-session' }
+  if (!state.candidate) {
+    return { active: true as const, kept: false as const, reason: 'no-candidate' }
+  }
+
+  const keptCandidate = state.candidate
+  const next: FlowSessionState = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+    steps: [...state.steps, keptCandidate.step],
+    candidate: null,
+  }
+  writeFlowSession(next)
+
+  return {
+    active: true as const,
+    kept: true as const,
+    candidate: keptCandidate,
+    stepCount: next.steps.length,
+  }
+}

package/cli/help-core.ts

@@ -0,0 +1,143 @@
+import { cliCommandMetas } from '@rnx/skills/cli'
+import {
+  renderCliCommandHelp,
+  renderCliGroupHelp,
+  renderCliIndexHelp,
+} from '@rnx/skills/cli/renderers'
+import { formatFlagHelp } from 'sootsim-engine/settings/cli-flags'
+import {
+  DEFAULT_SOOTSIM_BRIDGE_PORT,
+  DEFAULT_SOOTSIM_BRIDGE_URL,
+} from '../src/bridge-constants'
+import {
+  getRnxCommandAvailability,
+  getRnxFirstPositional,
+  getRnxCommandRegistration,
+  RNX_COMMAND_REGISTRY,
+} from './command-registry'
+import type { RnxBackendKind } from './command-contract'
+
+export interface RnxHelpOptions {
+  backend: RnxBackendKind
+  command?: string | null
+  commandArgs?: string[]
+  prefer?: 'command' | 'verb'
+  group?: string | null
+}
+
+const HELP_CONTEXT = {
+  bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
+  defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
+}
+
+function backendLabel(command: string, args: readonly string[]): string {
+  const available = (['node', 'browser'] satisfies RnxBackendKind[]).filter(
+    (backend) => getRnxCommandAvailability(command, args, backend).available,
+  )
+  return `available backends: ${available.join(', ')}`
+}
+
+function renderPreviewHelp(command: 'web' | 'ios' | 'android'): string {
+  return `rnx ${command} — select or ensure the current branch's existing ${command} preview
+
+usage:
+  rnx ${command}
+
+The browser backend selects the Factory-owned ${command} iframe. It never launches a
+host process or Cloudflare runtime.`
+}
+
+function renderFactoryBrowserLeaves(command: string): string | null {
+  switch (command) {
+    case 'do':
+      return `Factory browser leaves:
+  rnx do navigate /route`
+    case 'shell':
+      return `Factory browser leaves:
+  rnx shell appearance light|dark`
+    case 'assert':
+      return `Factory browser leaves:
+  rnx assert find (--testid <id>|--text <text>|--role <role>) [--exists|--empty] [--contains <text>]`
+    case 'screenshot':
+      return `Factory browser leaves:
+  rnx screenshot
+  rnx screenshot ask <question>
+  rnx screenshot appearance light|dark /route --by <query-kind> --value <target>
+  rnx screenshot motion <task-id> /route --trigger-by <kind> --trigger-value <target> --result-by <kind> --result-value <target> [--duration-ms <100..2000>]`
+    default:
+      return null
+  }
+}
+
+function renderRootAvailability(backend: RnxBackendKind): string {
+  const visibleCommands = new Set([
+    ...cliCommandMetas.filter((meta) => !meta.hidden).map((meta) => meta.id),
+    'web',
+    'ios',
+    'android',
+  ])
+  const visibleRegistry = RNX_COMMAND_REGISTRY.filter((entry) =>
+    visibleCommands.has(entry.name),
+  )
+  const available = visibleRegistry
+    .filter((entry) => getRnxCommandAvailability(entry.name, [], backend).available)
+    .map((entry) => entry.name)
+  const unavailable = visibleRegistry
+    .filter((entry) => !getRnxCommandAvailability(entry.name, [], backend).available)
+    .map((entry) => entry.name)
+
+  return `backend availability (${backend}):
+  available:   ${available.join(', ')}
+  unavailable: ${unavailable.join(', ')}
+
+Run \`rnx <command> --help\` for leaf availability and usage.`
+}
+
+export function renderRnxHelp(options: RnxHelpOptions): string {
+  const command = options.command ?? null
+  const commandArgs = options.commandArgs ?? []
+  if (!command) {
+    return `${renderCliIndexHelp(HELP_CONTEXT, formatFlagHelp()).trimEnd()}
+
+browser preview selectors:
+  rnx web                     select the existing Factory web preview
+  rnx ios                     select the existing Factory iOS preview
+  rnx android                 select the existing Factory Android preview
+
+${renderRootAvailability(options.backend)}`
+  }
+
+  let body: string | null
+  if (command === 'web' || command === 'ios' || command === 'android') {
+    body = renderPreviewHelp(command)
+  } else if (options.group === command && !options.prefer) {
+    body = renderCliGroupHelp(command, HELP_CONTEXT, formatFlagHelp())
+  } else {
+    const subVerb = getRnxFirstPositional(commandArgs)
+    const grouping = new Set(['do', 'get', 'debug', 'wait'])
+    const helpName = options.prefer === 'verb' && subVerb ? subVerb : command
+    body = renderCliCommandHelp(helpName, HELP_CONTEXT, {
+      prefer: options.prefer,
+      group: options.group,
+    })
+    if (!body && grouping.has(command)) {
+      body = renderCliGroupHelp(command, HELP_CONTEXT, formatFlagHelp())
+    }
+  }
+
+  if (!body) return `unknown command: ${command}`
+
+  const registration = getRnxCommandRegistration(command)
+  if (!registration) return body
+  const current = getRnxCommandAvailability(command, commandArgs, options.backend)
+  const currentLine = current.available
+    ? `${options.backend} backend: available`
+    : `${options.backend} backend: ${current.reason}`
+  const factoryLeaves =
+    options.backend === 'browser' ? renderFactoryBrowserLeaves(command) : null
+  return `${body.trimEnd()}
+
+${factoryLeaves ? `${factoryLeaves}\n\n` : ''}${backendLabel(command, commandArgs)}
+
+${currentLine}`
+}

package/cli/help.ts

@@ -0,0 +1,44 @@
+import { BETA_TAGLINE, IS_BETA } from '../src/beta'
+import { getCliVersion } from '../src/cli-version'
+import { rnxPublicBrand } from '../src/public-brand'
+import { renderRnxHelp } from './help-core'
+import { maybeHint } from './hints'
+import { getRuntimeSummary } from './runtime-summary'
+
+function versionSummaryLine(): string {
+  return `${rnxPublicBrand.commandName} CLI v${getCliVersion()} · ${getRuntimeSummary().primary}`
+}
+
+export function printHelp(): void {
+  const betaLine = IS_BETA ? `\n${BETA_TAGLINE}\n` : ''
+  console.log(
+    `${versionSummaryLine()}\n${betaLine}${renderRnxHelp({ backend: 'node' })}\n`,
+  )
+  maybeHint('clean-uninstall')
+}
+
+export function printGroupHelp(group: string): boolean {
+  const output = renderRnxHelp({
+    backend: 'node',
+    command: group,
+    group,
+  })
+  if (output.startsWith('unknown command:')) return false
+  console.log(`${output}\n`)
+  return true
+}
+
+export function printCommandHelp(
+  name: string,
+  options: { prefer?: 'command' | 'verb'; group?: string | null } = {},
+): void {
+  const command = options.group ?? name
+  const output = renderRnxHelp({
+    backend: 'node',
+    command,
+    commandArgs: options.group ? [name] : [],
+    prefer: options.prefer,
+    group: options.group,
+  })
+  console.log(`${output}\n`)
+}

package/cli/hidden-runtime-alias.ts

@@ -0,0 +1,19 @@
+import { getCliInspectVerbMetaByPath } from '@rnx/skills/cli'
+import type { ParsedArgs } from './parse-args'
+
+const HIDDEN_RUNTIME_ALIAS_GROUPS = ['do', 'get'] as const
+
+export function resolveHiddenRuntimeAlias(parsed: ParsedArgs): ParsedArgs {
+  if (parsed.command) return parsed
+
+  const attempted = parsed.commandArgs.find((arg) => !arg.startsWith('-'))
+  if (!attempted) return parsed
+
+  for (const group of HIDDEN_RUNTIME_ALIAS_GROUPS) {
+    if (getCliInspectVerbMetaByPath(group, attempted)) {
+      return { ...parsed, command: group }
+    }
+  }
+
+  return parsed
+}

package/cli/hints.ts

@@ -0,0 +1,214 @@
+// configurable, identity-scoped hint registry for the rnx CLI.
+//
+// two problems this solves:
+//   1. the CLI scatters "hint: ..." console.logs across many command files,
+//      each with slightly different wording.
+//   2. agents that loop over the same command (e.g. describe, find) see the
+//      same hint every invocation, which becomes noise.
+//
+// each hint declares its own frequency (always, once-per-identity, or a
+// cooldown), so hints that are informational-but-stale-quickly can still
+// re-fire while advice-like hints stay suppressed for the rest of the
+// CLI identity.
+//
+// suppression is keyed on `getCliIdentityKey()` so two agents / two terminals
+// don't share shown-sets.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join } from 'path'
+import { getCliIdentityKey } from './current-sim'
+
+export type HintFrequency =
+  | 'always'
+  | 'once-per-identity'
+  | 'once-ever'
+  | { cooldownMs: number }
+
+export interface HintSpec<Args extends unknown[] = unknown[]> {
+  frequency: HintFrequency
+  // returned string(s) are printed as-is, prefixed with two spaces.
+  // return null to skip (useful when render wants to decide conditionally).
+  render: (...args: Args) => string | string[] | null
+}
+
+const registry = new Map<string, HintSpec<any[]>>()
+
+export function defineHint<Args extends unknown[]>(id: string, spec: HintSpec<Args>) {
+  registry.set(id, spec as HintSpec<any[]>)
+}
+
+interface HintStateFile {
+  version: 1
+  shown: Record<string, number> // id -> last-shown timestamp (ms)
+}
+
+const STATE_VERSION = 1 as const
+
+function identityStatePath(): string {
+  return join(tmpdir(), `rnx-cli-hints-${getCliIdentityKey()}.json`)
+}
+
+function globalStatePath(): string {
+  return join(tmpdir(), `rnx-cli-hints-global.json`)
+}
+
+function readState(path: string): HintStateFile {
+  if (!existsSync(path)) return { version: STATE_VERSION, shown: {} }
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    if (parsed?.version !== STATE_VERSION || !parsed?.shown) {
+      return { version: STATE_VERSION, shown: {} }
+    }
+    return parsed as HintStateFile
+  } catch {
+    return { version: STATE_VERSION, shown: {} }
+  }
+}
+
+function writeState(path: string, state: HintStateFile) {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(state) + '\n')
+  } catch {
+    // best-effort only; losing shown state just means a hint re-fires once.
+  }
+}
+
+function modeFromEnv(): 'normal' | 'always' | 'off' {
+  const v = (process.env.RNX_HINTS || '').toLowerCase()
+  if (v === 'off' || v === '0' || v === 'false') return 'off'
+  if (v === 'always' || v === 'verbose') return 'always'
+  return 'normal'
+}
+
+function shouldShow(id: string, frequency: HintFrequency): boolean {
+  const mode = modeFromEnv()
+  if (mode === 'off') return false
+  if (mode === 'always') return true
+  if (frequency === 'always') return true
+
+  const now = Date.now()
+  if (frequency === 'once-per-identity') {
+    const state = readState(identityStatePath())
+    if (state.shown[id]) return false
+    state.shown[id] = now
+    writeState(identityStatePath(), state)
+    return true
+  }
+  if (frequency === 'once-ever') {
+    const state = readState(globalStatePath())
+    if (state.shown[id]) return false
+    state.shown[id] = now
+    writeState(globalStatePath(), state)
+    return true
+  }
+  if (typeof frequency === 'object' && 'cooldownMs' in frequency) {
+    const state = readState(identityStatePath())
+    const last = state.shown[id] ?? 0
+    if (now - last < frequency.cooldownMs) return false
+    state.shown[id] = now
+    writeState(identityStatePath(), state)
+    return true
+  }
+  return true
+}
+
+// print a registered hint. no-ops if suppressed for this identity/cooldown.
+// returns whether it was actually shown.
+export function maybeHint(id: string, ...args: unknown[]): boolean {
+  const spec = registry.get(id)
+  if (!spec) {
+    if (process.env.RNX_HINTS_DEBUG) {
+      console.error(`  [hints] no hint registered for id "${id}"`)
+    }
+    return false
+  }
+  if (!shouldShow(id, spec.frequency)) return false
+
+  const body = spec.render(...args)
+  if (body == null) return false
+  const lines = Array.isArray(body) ? body : [body]
+  // always stderr. every hint is advice about how to drive the CLI, never part
+  // of a command's result, and several commands (`describe`, `find`, every
+  // `do` verb) put a JSON document on stdout — a hint printed there corrupts it.
+  for (const line of lines) console.error(`  hint: ${line}`)
+  return true
+}
+
+export function resetHintsForIdentity() {
+  rmSync(identityStatePath(), { force: true })
+}
+
+export function resetGlobalHints() {
+  rmSync(globalStatePath(), { force: true })
+}
+
+export function listHints(): Array<{ id: string; frequency: HintFrequency }> {
+  return Array.from(registry.entries()).map(([id, spec]) => ({
+    id,
+    frequency: spec.frequency,
+  }))
+}
+
+// register the repo-wide hints here. keeping them centralised makes it easy
+// to audit wording + frequency policy in one place.
+defineHint<[number]>('app-still-loading', {
+  // re-fires once a minute because node count may genuinely change as the
+  // bundle boots — telling the user about it again is useful, not noisy.
+  frequency: { cooldownMs: 60_000 },
+  render: (nodeCount) =>
+    `app may still be loading (${nodeCount} nodes). run \`rnx wait ready\` first.`,
+})
+
+defineHint<[string]>('wait-selector-for-missing-testid', {
+  // advice is stable; once per CLI identity is enough.
+  frequency: 'once-per-identity',
+  render: (testId) => `rnx wait selector ${testId}`,
+})
+
+defineHint<[string[]]>('prefer-cli-over-eval', {
+  frequency: 'once-per-identity',
+  render: (suggestions) => {
+    if (!suggestions.length) return null
+    return [`try the CLI shortcut instead:`, ...suggestions.map((s) => `  ${s}`)]
+  },
+})
+
+defineHint<[]>('describe-use-filters', {
+  // shown when a describe run emits >=80 lines without any filter active —
+  // gentle nudge that there are better tools.
+  frequency: 'once-per-identity',
+  render: () => [
+    `describe output is long. narrow it with:`,
+    `  rnx describe --only '*Bottom Sheet*'`,
+    `  rnx describe --testid-like 'swap-*'`,
+    `  rnx describe --subtree <testID>`,
+  ],
+})
+
+defineHint<[]>('describe-filter-context', {
+  // filtered describe is useful search output, but it intentionally drops
+  // surrounding tree context. once per identity is enough to prevent agents
+  // treating a search hit as route proof.
+  frequency: 'once-per-identity',
+  render: () => [
+    `filtered describe is search output, not current-route proof.`,
+    `run \`rnx describe\` without filters after navigation; clipped nodes are marked \`(clipped:...)\`.`,
+  ],
+})
+
+defineHint<[string]>('subtree-root-not-found', {
+  frequency: 'always',
+  render: (id) =>
+    `no node with testID/id "${id}" — try \`rnx find --testid ${id}\` to discover available ids.`,
+})
+
+defineHint<[]>('clean-uninstall', {
+  // shown once on the first `rnx --help` run so users learn the teardown path.
+  frequency: 'once-ever',
+  render: () => [
+    `to remove the background daemon, run \`rnx daemon uninstall\`. it keeps your runtimes and device profiles; add \`--purge\` to delete ~/.rnx too.`,
+    `the optional desktop app and its macOS preference plist are separate from the daemon.`,
+  ],
+})