rnxsim 0.0.0 → 0.1.313

package/scripts/optional-demo-registry.ts

@@ -0,0 +1,113 @@
+// optional, best-effort access to the INTERNAL demo-app registry
+// (`./demo-app-registry.ts`). that file is repo-internal dev tooling: it pins
+// real demo apps to fixed ports (e.g. 3pc on 8081) and is consumed only by
+// `bun run demo` + the in-repo electron/vite discovery paths, which run from
+// the typescript source where the registry is always present.
+//
+// the PUBLISHED `sootsim` npm package must know nothing about those internal
+// apps — shipping the registry once matched a brand-new user's `expo start` on
+// the default port 8081 against the 3pc `one` entry and crashed their metro
+// (repo-agnostic-pipeline violation). so the registry is NOT in the package
+// `files` list, and the `import()` below is resolved to an absolute path at
+// runtime: it finds the source registry in-repo and nothing (empty list) on a
+// published install. no bundler can see through that, so it never inlines.
+//
+// one path, no env toggle: every consumer goes through this loader; whether the
+// registry resolves is purely a function of whether the file exists on disk.
+
+import { existsSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// this module is emitted at three different depths — the source at
+// packages/sootsim/scripts/, the built CLI at packages/sootsim/dist-cli/chunks/,
+// and the electron main bundle at packages/sootsim-engine/dist-electron/ — so a
+// relative './demo-app-registry.ts' is only correct from the source copy. from
+// the other two it points at a file that does not exist, the catch below
+// swallows that, and every demo app then boots with no runtimeConfig at all
+// (mattermost stops on the server-select screen because AutoSelectServerUrl
+// never reaches it). the one description that holds from every emit site is the
+// ancestor that holds the registry at its repo path, which in-repo is the
+// monorepo root.
+const REGISTRY_REPO_PATH = 'packages/sootsim/scripts/demo-app-registry.ts'
+
+// the walk must never leave the installed package. `sootsim` publishes this
+// loader's source, so on a published install it runs from
+// node_modules/sootsim/scripts/ (or dist-cli/chunks/) with the consumer's whole
+// filesystem above it — and consumers include this repo's own templates and
+// examples, which install sootsim while sitting inside the monorepo. an
+// unbounded walk from there reaches the real registry and hands a user's
+// `expo start` on port 8081 the internal 3pc entry, which is the exact incident
+// the header describes. a node_modules ancestor means "installed as a
+// dependency", so the search stops there and the registry stays absent.
+const MAX_ANCESTOR_STEPS = 8
+
+/** absolute path to the internal registry, or null when this copy is running
+ *  outside the monorepo (a published install) and must not have one. */
+export function findInternalDemoRegistry(startDir: string): string | null {
+  let dir = startDir
+  for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
+    if (basename(dir) === 'node_modules') return null
+    const candidate = join(dir, REGISTRY_REPO_PATH)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+  return null
+}
+
+export interface OptionalDemoApp {
+  name: string
+  label: string
+  dir: string
+  preferredPort: number
+  framework: 'expo' | 'one' | 'rock'
+  runtimeConfig?: import('../src/config.ts').SootSimConfig
+}
+
+let cached: OptionalDemoApp[] | null = null
+
+/** load the internal demo registry if it's present on disk (in-repo only).
+ *  returns [] on a published install where the registry was not shipped. */
+export async function loadOptionalDemoApps(): Promise<OptionalDemoApp[]> {
+  if (cached) return cached
+  const registryPath = findInternalDemoRegistry(dirname(fileURLToPath(import.meta.url)))
+  if (!registryPath) {
+    cached = []
+    return cached
+  }
+  try {
+    const mod = (await import(/* @vite-ignore */ pathToFileURL(registryPath).href)) as {
+      APPS?: OptionalDemoApp[]
+    }
+    cached = Array.isArray(mod.APPS) ? mod.APPS : []
+  } catch {
+    cached = []
+  }
+  return cached
+}
+
+/** synchronous view of the registry — empty until `loadOptionalDemoApps()` has
+ *  resolved at least once. every caller that builds a result from the registry
+ *  awaits the load first. */
+export function optionalDemoAppsSync(): OptionalDemoApp[] {
+  return cached ?? []
+}
+
+/** replace the registry with a fixed list, and restore it on the returned
+ *  handle. what the real registry holds depends on which third-party app
+ *  checkouts and credential files happen to exist on the machine, so a test
+ *  that reads it asserts on the developer's home directory rather than on the
+ *  code. it passes on the box that has them and fails everywhere else. */
+export function __withOptionalDemoAppsForTests(apps: OptionalDemoApp[]): {
+  restore: () => void
+} {
+  const previous = cached
+  cached = apps
+  return {
+    restore: () => {
+      cached = previous
+    },
+  }
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// npm installs package code only. `sootsim setup` owns runtime and machine
+// changes so installs never download a runtime or register a service implicitly.

package/scripts/preuninstall.cjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// preuninstall — runs before `npm rm -g sootsim` actually removes the bin.
+//
+// without this hook the user is left with a 79MB ghost: a launchd/systemd
+// service still ENABLED + actively running (with ExecStart pointing at the
+// now-missing binary), ~/.sootsim/ (cache + runtimes + electron + profiles +
+// daemon.json), and the user's first instinct (`sootsim daemon uninstall`)
+// is gone with the package. so we tear it all down here, while the bin still
+// exists.
+//
+// reliability: npm preuninstall hooks are best-effort — they don't fire when
+// the package wasn't installed by npm (yarn/bun/pnpm have their own lifecycle
+// rules), and they don't run as part of `npm cache verify` cleanup or manual
+// dir removal. that's why `sootsim daemon uninstall` is also documented as
+// the manual teardown path.
+//
+// strategy: spawn the bundled bin to run `daemon uninstall` (single source of
+// truth — the same logic the user invokes manually). if that fails for any
+// reason — node version mismatch, the bin already removed by a previous
+// half-completed run, missing $HOME — do a best-effort raw fs cleanup so the
+// machine isn't left in a broken state.
+
+const { spawnSync } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+if (process.env.SOOTSIM_SKIP_PREUNINSTALL === '1') {
+  process.exit(0)
+}
+
+// dev / workspace installs (running inside the Contrast monorepo, not in a
+// node_modules tree) — don't tear anything down. the developer is rebuilding
+// the workspace, not actually uninstalling.
+const pkgDir = path.resolve(__dirname, '..')
+if (!pkgDir.includes(`${path.sep}node_modules${path.sep}`)) {
+  process.exit(0)
+}
+
+// skipped under sudo for the same reason as postinstall: $HOME would be /root,
+// but the user who needs cleanup is the one who installed sootsim. they can
+// run `sootsim daemon uninstall` themselves before `sudo npm rm -g sootsim`
+// to clean their own home.
+const isRoot = typeof process.getuid === 'function' && process.getuid() === 0
+if (isRoot && process.env.SUDO_USER) {
+  console.log(
+    'rnx: preuninstall skipped under sudo — run `rnxsim daemon uninstall` ' +
+      'as your user first to remove ~/.sootsim and the bridge daemon',
+  )
+  process.exit(0)
+}
+
+const bin = path.join(pkgDir, 'dist-cli', 'bin.js')
+let unifiedOk = false
+if (fs.existsSync(bin)) {
+  const res = spawnSync(process.execPath, [bin, 'daemon', 'uninstall'], {
+    stdio: 'inherit',
+    timeout: 30_000,
+  })
+  unifiedOk = res.status === 0
+}
+
+if (!unifiedOk) {
+  // raw fallback. mirrors teardownDaemonService + teardownSootsimHome from
+  // cli/commands/daemon.ts. idempotent: each entry is checked before remove.
+  console.log('rnx: bin path failed — running raw cleanup fallback')
+  rawCleanup()
+}
+
+process.exit(0)
+
+function rawCleanup() {
+  const home = sootsimHomeDir()
+  if (process.platform === 'darwin') {
+    safeSpawn('launchctl', ['bootout', `gui/${getuid()}/dev.sootsim.daemon`])
+    safeSpawn('launchctl', ['bootout', `gui/${getuid()}/dev.sootsim.server`])
+    safeRemove(path.join(os.homedir(), 'Library/LaunchAgents/dev.sootsim.daemon.plist'))
+    safeRemove(path.join(os.homedir(), 'Library/LaunchAgents/dev.sootsim.server.plist'))
+    safeRemove(path.join(os.homedir(), 'Library/Logs/sootsim'), {
+      recursive: true,
+    })
+  } else if (process.platform === 'linux') {
+    safeSpawn('systemctl', ['--user', 'disable', '--now', 'sootsim-daemon'])
+    safeSpawn('systemctl', ['--user', 'daemon-reload'])
+    safeSpawn('systemctl', ['--user', 'reset-failed', 'sootsim-daemon'])
+    safeRemove(path.join(os.homedir(), '.config/systemd/user/sootsim-daemon.service'))
+    safeRemove(path.join(os.homedir(), '.local/state/sootsim'), { recursive: true })
+  }
+  // ~/.sootsim is the same on every platform; honor $SOOTSIM_HOME.
+  safeRemove(home, { recursive: true })
+}
+
+function sootsimHomeDir() {
+  const env = process.env.SOOTSIM_HOME
+  if (env && env.length > 0) return path.resolve(env)
+  return path.join(os.homedir(), '.sootsim')
+}
+
+function safeRemove(p, opts) {
+  try {
+    if (fs.existsSync(p)) {
+      fs.rmSync(p, { force: true, ...(opts || {}) })
+      console.log(`  removed ${p}`)
+    }
+  } catch (err) {
+    console.log(`  could not remove ${p}: ${err && err.message}`)
+  }
+}
+
+function safeSpawn(cmd, args) {
+  try {
+    spawnSync(cmd, args, { stdio: 'ignore' })
+  } catch {}
+}
+
+function getuid() {
+  return typeof process.getuid === 'function' ? process.getuid() : 0
+}

package/skills/contrast/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: contrast
+description: >-
+  index of all Contrast and rnx agent skills and CLI commands.
+  auto-generated from the CLI info registry — do not edit by hand.
+---
+
+# contrast
+
+overview of all available skills and CLI commands in this repo.
+
+> this file is auto-generated by `bun scripts/generate-contrast-skill.ts`.
+> to update, edit the source registries and re-run the generator.
+
+## rnx CLI commands
+
+the `rnxsim` CLI is the operational surface for booting shells, driving
+automation, inspecting the render tree, and managing sims.
+
+| command | description |
+| --- | --- |
+| `rnxsim maestro` | author, generate, and run Maestro YAML flows against rnx |
+| `rnxsim detox` | run existing Detox suites against rnx on headless Chromium |
+| `rnxsim cleanup` | inspect and reclaim local rnx disk usage |
+| `rnxsim record` | capture the live sim as webm/mp4/gif, or sample N png frames (--frames) |
+| `rnxsim film` | record a flow on the flat canvas, replay it on the 3d device stage under a camera cinematic, save a clip |
+| `rnxsim storage` | manage guest app storage and launch profiles |
+| `rnxsim permissions` | inspect and change simulated operating-system permissions |
+| `rnxsim perf` | CPU, React render, shell frame, and scroll-layer profiling |
+| `rnxsim describe` | curated human-readable UI summary (default inspection tool) |
+| `rnxsim find` | locate nodes by text / testID / role / type / predicate |
+| `rnxsim assert` | run any read verb and convert its output into an exit code |
+| `rnxsim screenshot` | capture PNGs and manage App Store screenshot assets |
+| `rnxsim get` | read runtime state (tree, a11y, layout, url, count, errors, …) |
+| `rnxsim do` | drive the app (tap, type, scroll, swipe, key, reload, …) |
+| `rnxsim wait` | block until the runtime reaches a known state |
+| `rnxsim shell` | drive shell state and simulator chrome |
+| `rnxsim mode` | toggle screenshot and 3D display modes |
+| `rnxsim device` | inspect or change the live device preset for a sim |
+| `rnxsim inspect` | query, describe, and drive the running rnx instance |
+| `rnxsim network` | inspect live network traffic from the running rnx worker |
+| `rnxsim logs` | inspect live console output from the running rnx worker |
+| `rnxsim debug` | drive __sootsimDebug: channels, snapshots, and inspectors |
+| `rnxsim what-happened` | show recent semantic events: toasts, keyboards, screens, alerts, fetches, errors |
+| `rnxsim timeline` | control the semantic event timeline (enable opt-in kinds, clear, dump) |
+| `rnxsim open` | load a target into the current sim or open a new one |
+| `rnxsim list` | list connected sims or available launch drivers |
+| `rnxsim use` | select a connected sim |
+| `rnxsim skill` | install and inspect bundled rnx agent skills |
+| `rnxsim claim` | take an exclusive lease on a sim |
+| `rnxsim agent` | attached projects + local agent sessions (codex/claude) |
+| `rnxsim close` | close a connected sim |
+| `rnxsim setup` | check local setup and install the recommended bridge daemon |
+| `rnxsim compat` | check package compatibility |
+| `rnxsim report-issue` | send an explicitly approved compatibility report |
+| `rnxsim desktop` | launch or install the desktop companion |
+| `rnxsim daemon` | manage the optional background bridge service |
+| `rnxsim version` | show the CLI + engine runtime versions you are running |
+| `rnxsim upgrade` | update the rnxsim CLI and engine runtime to the latest |
+| `rnxsim serve` | run the rnx bridge in the foreground |
+| `rnxsim runtime` | manage engine runtimes under ~/.sootsim/runtimes/ |
+| `rnxsim auth` | inspect active CLI auth |
+| `rnxsim login` | sign in for preview uploads |
+| `rnxsim logout` | clear the local desktop auth session |
+| `rnxsim config` | manage local CLI preferences |
+
+### runtime verb groups
+
+every runtime verb is organized under one of these grouping prefixes.
+run `rnxsim --help` to see the full list under each group.
+
+- `rnxsim describe` — summarize the current UI
+- `rnxsim find <...>` — unified finder (bare text, --testid, --role, --type, --pressable, --visible)
+- `rnxsim get <noun>` — read runtime state (tree, a11y, url, count, errors, warnings, requests, globals, layout, node)
+- `rnxsim do <action>` — drive the app (tap, tap-text, tap-id, type, type-into, key, dismiss, scroll, drag, swipe, pinch, reload, shell, sleep, settle, wait)
+- `rnxsim debug <tool>` — instrumentation (state, js, eval, perf, sample-color, enable/disable channels, snapshots, diff, record, recent)
+
+### global flags
+
+- `-h, --help` — show help
+- `-V, --version` — show version
+- `-v, --verbose` — verbose output
+- `-p, --port <number>` — bridge port, depending on command
+- `-d, --device <model>` — override the simulated device model
+- `-t, --theme <scheme>` — override light, dark, or auto color scheme
+- `--headless` — run browser automation without a visible window where supported
+
+## bundled rnx agent skills
+
+skills for working with the rnx native preview engine:
+
+| skill | description |
+| --- | --- |
+| `/rnx-debug` | Debug rendering, animation, gesture, performance, and accessibility issues in a React Native app running under rnx. Reach for this whenever an animation looks wrong (janky, stutters, snaps, only updates once, or doesn't move at all), a swipe/transition/gesture misbehaves or feels broken, scrolling drops frames or feels slow, the UI renders the wrong tree/props, or a screen reader can't reach something — and drive the rnxsim CLI debug tooling first, not screenshots or ad-hoc logging. |
+| `/rnx-perf` | Optimize rnx engine and app performance — scroll jank, dropped frames, slow animation, idle CPU, memory growth, and "smooth normally but laggy under load" (video calls, busy machines). Covers measuring on the right thread with the right browser, proving each perf tier actually engages via its counters, a CPU-contention test harness, and the map of existing perf machinery so you improve it instead of reinventing it. For general app debugging load /rnx-debug first. |
+| `/rnx-setup` | Get rnx connected to your React Native app — from `rnxsim setup` to a driveable sim |
+| `/rnx-test` | Run automated tests against your React Native app under rnx with Maestro YAML or Detox/Jest |
+| `/rnx-visual` | Pixel-level rendering comparison between rnx and native iOS — fonts, gradients, shadows, image fidelity |
+
+## automatic settling
+
+every CLI command already waits at the right moment — **do not wrap
+commands in your own `sleep` or chain `do settle` "just to be safe"**.
+
+- **before read commands** (`describe`, `find`, `get`, `tree`, `node`,
+  `layout`, `screenshot`, `capture`, `a11y`, `sample-color`, `count`,
+  and every gesture — `tap`, `tap-id`, `tap-text`, `type-into`,
+  `touch`, `swipe`, `drag`, `scroll`, `pinch`, `long-press`,
+  `double-tap`, `gesture`) the CLI waits up to **1800 ms** for any
+  in-flight screen transition to actually start, so the tree you read is
+  never mid-flip.
+- **after write commands** (`tap`, `tap-text`, `tap-id`, `type`,
+  `type-into`, `key`, `key-sequence`, `keycode`, `drag`, `swipe`,
+  `long-press`, `touch`, `gesture`, `pinch`, `scroll`, `shell`)
+  the CLI polls the layout hash until it is stable for two consecutive
+  frames. budget: **400 ms for agents** (`SOOTSIM_AGENT=1`, set by the
+  harness), 200 ms for humans.
+
+what this means:
+
+- `rnxsim do tap-id login` then `rnxsim find "Welcome"` Just Works™.
+- you only need `rnxsim do settle <seconds>` or `rnxsim wait idle
+  --max-ms <N>` when the CLI explicitly prints
+  `⚠ auto-wait timed out after Nms — next command may see mid-animation
+  state`, or when the transition you care about lasts longer than ~400 ms
+  (full stack navigation, crossfades, video load).
+- opt-out: `--no-wait` on a single command, `SOOTSIM_NO_AUTO_WAIT=1`
+  for a whole lane.
+- if a read keeps racing its write, the fix is **never** a blind `sleep` —
+  prefer `wait selector`, `wait ready`, `wait idle`, or a longer
+  explicit `do settle`, and investigate whether the app's animation
+  completion signal is actually firing.
+
+## quick reference
+
+### dev workflow
+
+```sh
+bun dev                              # start everything
+rnxsim dev -- pnpm dev              # wrap a bundler
+rnxsim open 8081                    # load an app
+rnxsim describe                     # inspect the UI tree
+```
+
+### debugging
+
+```sh
+rnxsim get errors 5                 # recent console errors
+rnxsim get requests 5               # recent failed requests
+rnxsim debug snapshot before        # capture state
+rnxsim debug diff before after      # compare snapshots
+rnxsim debug state shell            # runtime state dump
+```
+
+### testing
+
+```sh
+rnxsim maestro test .maestro/       # run Maestro YAML flows
+rnxsim maestro generate "login"     # generate and run a Maestro flow
+rnxsim detox                        # run Detox/Jest suites
+```
+
+### inspection
+
+```sh
+rnxsim describe                     # visible elements
+rnxsim find "Sign in"               # find by text
+rnxsim find --testid loginButton    # find by testID
+rnxsim do tap-text "Submit"         # tap by text
+rnxsim do type "hello"              # type text
+```