rnxsim 0.1.312 → 0.1.314

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 `sootsim 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 sootsim. 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 sootsim 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 `sootsim 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 sootsim 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 `sootsim 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-file.ts

@@ -0,0 +1,142 @@
+import * as fs from 'fs'
+import yaml from 'yaml'
+
+export interface FlowFrontmatter {
+  // raw `sootsim 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 sootsim (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. sootsim 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 sootsim.
+//
+// `${...}` 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 `sootsim 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}`]
+  }
+}

package/cli/flow-live-status.ts

@@ -0,0 +1,120 @@
+// 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 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 },
+          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 })
+  }
+
+  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,187 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { dirname, join, resolve } from 'path'
+import yaml from 'yaml'
+import { validateFlowSteps } from './flow-file'
+
+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.SOOTSIM_FLOW_SESSION_PATH || join(tmpdir(), 'sootsim-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,
+  }
+}
+
+export function formatFlowDraftYaml(steps: FlowDraftStep[]) {
+  return yaml.stringify(steps).trimEnd() + '\n'
+}
+
+export function exportFlowSession(outputPath?: string) {
+  const state = readFlowSession()
+  if (!state) return { active: false as const }
+
+  const yamlText = formatFlowDraftYaml(state.steps)
+  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/help.ts

@@ -0,0 +1,80 @@
+import {
+  renderCliCommandHelp,
+  renderCliGroupHelp,
+  renderCliIndexHelp,
+} from '@sootsim/skills/cli/renderers'
+import { formatFlagHelp } from 'sootsim-engine/settings/cli-flags'
+import { BETA_TAGLINE, IS_BETA } from '../src/beta'
+import {
+  DEFAULT_SOOTSIM_BRIDGE_PORT,
+  DEFAULT_SOOTSIM_BRIDGE_URL,
+} from '../src/bridge-constants'
+import { getCliVersion } from '../src/cli-version'
+import { rnxPublicBrand } from '../src/public-brand'
+import { maybeHint } from './hints'
+import { getRuntimeSummary } from './runtime-summary'
+
+// header line shown at the top of `--help` so users can always tell what
+// they're running — the CLI npm version and the active engine runtime
+// version are independent, which is exactly the confusion `sootsim
+// upgrade` exists to clear up.
+function versionSummaryLine(): string {
+  return `${rnxPublicBrand.commandName} CLI v${getCliVersion()} · ${getRuntimeSummary().primary}`
+}
+
+export function printHelp() {
+  const base = renderCliIndexHelp(
+    {
+      bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
+      defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
+    },
+    formatFlagHelp(),
+  )
+  const betaLine = IS_BETA ? `\n${BETA_TAGLINE}\n` : ''
+  console.log(
+    `${versionSummaryLine()}\n${betaLine}${base}
+`,
+  )
+  // once-ever nudge so users learn the clean teardown path before they need it.
+  // the npm preuninstall hook runs the same teardown automatically when it
+  // fires; this is the documented manual fallback.
+  maybeHint('clean-uninstall')
+}
+
+// bare `sootsim` prints the registry-backed surface. setup/open own work.
+
+// print the help page for a grouping verb (do / get / debug / wait) built
+// entirely from the registry — no hardcoded strings. returns true if the
+// group was known, false if the caller should fall through.
+export function printGroupHelp(group: string): boolean {
+  const output = renderCliGroupHelp(
+    group,
+    {
+      bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
+      defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
+    },
+    formatFlagHelp(),
+  )
+  if (!output) return false
+  console.log(`${output}\n`)
+  return true
+}
+
+export function printCommandHelp(
+  name: string,
+  options: { prefer?: 'command' | 'verb'; group?: string | null } = {},
+) {
+  const output = renderCliCommandHelp(
+    name,
+    {
+      bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
+      defaultShellUrl: DEFAULT_SOOTSIM_BRIDGE_URL,
+    },
+    options,
+  )
+  if (!output) {
+    console.log(`unknown command: ${name}`)
+    return
+  }
+  console.log(`${output}\n`)
+}