rnxsim 0.1.312 → 0.1.314

package/cli/commands/runtime.ts

@@ -0,0 +1,351 @@
+// sootsim runtime — manage engine runtimes under ~/.sootsim/runtimes/.
+//
+// runtimes are versioned tarballs hosted behind the configured CDN origin
+// (default https://contrast.dev/runtimes/). each install:
+//   1. fetches manifest.json to resolve a version (or confirm the literal)
+//   2. downloads sootsim-runtime-<version>.tar.gz to an operation temp directory
+//   3. verifies sha256
+//   4. extracts to ~/.sootsim/runtimes/<version>/
+//   5. (optionally) sets it active + tells the daemon to hot-swap
+//
+// the daemon-side state (active runtime) is mirrored in ~/.sootsim/runtimes/active
+// so the CLI can change it even when the daemon isn't running.
+
+import fs from 'fs'
+import { compareSemver } from '@contrast/runtime-delivery'
+import { WebSocket } from 'ws'
+import {
+  ensureSootsimHome,
+  readActiveRuntime,
+  readLiveRuntimeVersions,
+  runtimeDir,
+  writeActiveRuntime,
+} from '../../src/home-paths'
+import {
+  DEFAULT_RUNTIME_CDN_ORIGIN,
+  SOOTSIM_CHANGELOG_URL,
+  sootsimRuntime,
+} from '../../src/runtime-delivery'
+import { resolveSootSimAppConfig } from '../app-config'
+import { fetchRuntimeReleaseNotes, formatRuntimeReleaseNotes } from '../runtime-notes'
+import { resolveDefaultBridgePort } from '../ws-bridge'
+
+interface RuntimeOptions {
+  channel?: string
+}
+
+export async function runRuntime(args: string[], opts: RuntimeOptions = {}) {
+  const [sub, ...rest] = args
+  if (!sub || sub === '--help' || sub === '-h') {
+    printHelp()
+    return
+  }
+  switch (sub) {
+    case 'install':
+      return runtimeInstall(rest, opts)
+    case 'list':
+    case 'ls':
+      return runtimeList(rest)
+    case 'use':
+      return runtimeUse(rest)
+    case 'remove':
+    case 'rm':
+      return runtimeRemove(rest)
+    case 'which':
+    case 'active':
+      return runtimeWhich()
+    case 'notes':
+    case 'changelog':
+      return runtimeNotes(rest)
+    default:
+      console.error(`  unknown runtime subcommand: ${sub}`)
+      printHelp()
+      process.exit(1)
+  }
+}
+
+function printHelp() {
+  console.log(`
+rnxsim runtime — manage engine runtimes under ~/.sootsim/runtimes/
+
+usage:
+  rnxsim runtime install [version]   install a version (default: channel latest)
+  rnxsim runtime list                show installed + available versions
+  rnxsim runtime use <version>       switch active runtime
+  rnxsim runtime remove <version>    delete an installed runtime
+  rnxsim runtime which               print active runtime version
+  rnxsim runtime notes               print repo or default engine release notes
+
+flags:
+  --channel <name>    channel to resolve 'latest' from (default: stable)
+  --force             reinstall even if the version is already on disk
+  --set-active=false  do not switch active runtime after install
+
+environment:
+  SOOTSIM_CDN_ORIGIN  override the CDN base URL (default: ${DEFAULT_RUNTIME_CDN_ORIGIN})
+
+examples:
+  rnxsim runtime install
+  rnxsim runtime install 1.2.3
+  rnxsim runtime install --channel beta
+  rnxsim runtime use 1.2.3
+  rnxsim runtime notes
+`)
+}
+
+// --- install --------------------------------------------------------------
+
+async function runtimeInstall(args: string[], opts: RuntimeOptions) {
+  const { version: versionArg, flags } = parseVersionAndFlags(args)
+  const channel = flags.channel ?? opts.channel ?? 'stable'
+  const force = flags.force === true
+  const setActive = flags.setActive !== false
+
+  ensureSootsimHome()
+
+  console.log(`rnxsim runtime install`)
+  console.log(`  cdn:     ${sootsimRuntime.resolveCdnOrigin()}`)
+
+  try {
+    const result = await sootsimRuntime.install({
+      version: versionArg,
+      channel,
+      force,
+      setActive,
+      protectVersions: readLiveRuntimeVersions(),
+    })
+    console.log(`  version: ${result.version} (channel: ${result.channel})`)
+    if (result.installed) {
+      console.log(`  installed ${result.version}`)
+    } else {
+      console.log(`  already installed at ${result.runtimeDir}`)
+    }
+    if (setActive) await activateVersion(result.version)
+    return result
+  } catch (err) {
+    console.error(`  ${describeError(err)}`)
+    process.exit(1)
+  }
+}
+
+async function activateVersion(version: string) {
+  writeActiveRuntime(version)
+  console.log(`  active:  ${version}`)
+  // if a daemon is running, tell it to hot-swap its http root. the
+  // daemon re-reads the active runtime per-request anyway, so this is
+  // mostly a nudge — but it also broadcasts runtime:changed so any
+  // connected electron webContents can reload. silent failure is fine;
+  // the next daemon start picks up the active file from disk.
+  const notified = await tellDaemonRuntimeChanged(version)
+  if (!notified) {
+    console.log(
+      `  (no daemon running — next sootsim/electron launch will pick up ${version})`,
+    )
+  }
+}
+
+/** notify a running daemon that the active runtime changed so it hot-swaps
+ *  its http root + pushes a runtime:changed message to every connected
+ *  browser (electron). uses a raw WebSocket to skip the bridge's
+ *  primary-browser resolution — this message is daemon-only, not routed
+ *  to a browser. returns true when the daemon acknowledged; false when
+ *  no fresh daemon was reachable (caller logs accordingly).
+ *
+ *  skips the ws probe entirely when the lockfile isn't fresh — the
+ *  default-port fallback in resolveDefaultBridgePort() would otherwise
+ *  eat a full handshakeTimeout on every `runtime use` when no daemon
+ *  is running. */
+async function tellDaemonRuntimeChanged(version: string): Promise<boolean> {
+  const { isDaemonLockfileFresh, readDaemonLockfile } =
+    await import('../../src/home-paths')
+  const lock = readDaemonLockfile()
+  if (!isDaemonLockfileFresh(lock)) return false
+  const port = resolveDefaultBridgePort()
+  return new Promise<boolean>((resolve) => {
+    let settled = false
+    let success = false
+    const finish = (ok: boolean) => {
+      if (settled) return
+      settled = true
+      resolve(ok)
+    }
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`, {
+      handshakeTimeout: 800,
+    })
+    const timer = setTimeout(() => {
+      try {
+        ws.close()
+      } catch {}
+      finish(success)
+    }, 1500)
+    ws.on('open', () => {
+      try {
+        ws.send(JSON.stringify({ type: 'runtime:use', version, id: 0 }))
+        success = true
+      } catch {}
+      // give the daemon a beat to process, then close
+      setTimeout(() => {
+        try {
+          ws.close()
+        } catch {}
+      }, 100)
+    })
+    ws.on('close', () => {
+      clearTimeout(timer)
+      finish(success)
+    })
+    ws.on('error', () => {
+      clearTimeout(timer)
+      finish(false)
+    })
+  })
+}
+
+// --- list -----------------------------------------------------------------
+
+async function runtimeList(_args: string[]) {
+  ensureSootsimHome()
+  const installed = sootsimRuntime.listInstalled()
+  const active = readActiveRuntime()
+  console.log(`installed:`)
+  if (installed.length === 0) {
+    console.log(`  (none)`)
+  } else {
+    for (const v of installed) {
+      const marker = v === active ? '*' : ' '
+      console.log(`  ${marker} ${v}`)
+    }
+  }
+  try {
+    const manifest = await sootsimRuntime.fetchManifest()
+    console.log(`available (latest per channel):`)
+    for (const [name, ch] of Object.entries(manifest.channels)) {
+      console.log(`  ${name.padEnd(8)} ${ch.latest}`)
+    }
+    const hosted = Object.keys(manifest.versions).sort(compareSemver).reverse()
+    if (hosted.length > 1) {
+      console.log(`hosted versions:`)
+      for (const v of hosted) console.log(`  ${v}`)
+    }
+  } catch (err) {
+    console.log(`available: (could not fetch manifest: ${describeError(err)})`)
+  }
+}
+
+// --- use ------------------------------------------------------------------
+
+async function runtimeUse(args: string[]) {
+  const version = args[0]
+  if (!version) {
+    console.error(`  usage: rnxsim runtime use <version>`)
+    process.exit(1)
+  }
+  const installed = sootsimRuntime.listInstalled()
+  if (!installed.includes(version)) {
+    console.error(`  version ${version} is not installed`)
+    console.error(`  installed: ${installed.join(', ') || '(none)'}`)
+    console.error(`  run \`rnxsim runtime install ${version}\` first`)
+    process.exit(1)
+  }
+  await activateVersion(version)
+}
+
+// --- remove ---------------------------------------------------------------
+
+async function runtimeRemove(args: string[]) {
+  const version = args[0]
+  if (!version) {
+    console.error(`  usage: rnxsim runtime remove <version>`)
+    process.exit(1)
+  }
+  const active = readActiveRuntime()
+  if (active === version) {
+    console.error(`  cannot remove active runtime ${version}`)
+    console.error(
+      `  switch with \`rnxsim runtime use <other>\` first, or install another version`,
+    )
+    process.exit(1)
+  }
+  if (readLiveRuntimeVersions().includes(version)) {
+    console.error(`  cannot remove runtime ${version} while a project is using it`)
+    process.exit(1)
+  }
+  const dir = runtimeDir(version)
+  if (!fs.existsSync(dir)) {
+    console.error(`  ${version} is not installed`)
+    return
+  }
+  fs.rmSync(dir, { recursive: true, force: true })
+  console.log(`  removed ${version}`)
+}
+
+// --- which ----------------------------------------------------------------
+
+async function runtimeWhich() {
+  const active = readActiveRuntime()
+  if (!active) {
+    console.log(`  no active runtime`)
+    return
+  }
+  console.log(active)
+}
+
+// --- notes ----------------------------------------------------------------
+
+async function runtimeNotes(args: string[]) {
+  if (args.length > 0) {
+    console.error(`  usage: rnxsim runtime notes`)
+    process.exit(1)
+  }
+  const { config } = await resolveSootSimAppConfig()
+  const version = config?.runtimeVersion ?? readActiveRuntime()
+  if (!version) {
+    console.log(`  no active runtime`)
+    console.log(`  release notes: ${SOOTSIM_CHANGELOG_URL}`)
+    return
+  }
+  console.log(formatRuntimeReleaseNotes(version, await fetchRuntimeReleaseNotes(version)))
+}
+
+// --- helpers --------------------------------------------------------------
+
+interface InstallFlags {
+  channel?: string
+  force?: boolean
+  setActive?: boolean
+}
+
+function parseVersionAndFlags(args: string[]): {
+  version: string | null
+  flags: InstallFlags
+} {
+  const flags: InstallFlags = {}
+  const positional: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--channel' && i + 1 < args.length) {
+      flags.channel = args[i + 1]
+      i++
+      continue
+    }
+    if (arg.startsWith('--channel=')) {
+      flags.channel = arg.slice('--channel='.length)
+      continue
+    }
+    if (arg === '--force') {
+      flags.force = true
+      continue
+    }
+    if (arg === '--set-active=false' || arg === '--no-set-active') {
+      flags.setActive = false
+      continue
+    }
+    positional.push(arg)
+  }
+  return { version: positional[0] ?? null, flags }
+}
+
+function describeError(err: unknown): string {
+  if (err instanceof Error) return err.message
+  return String(err)
+}

package/cli/commands/screenshot-command.ts

@@ -0,0 +1,106 @@
+import { runScreenshot } from './screenshot'
+import { runScreenshots } from './screenshots'
+import { runSlides } from './slides'
+
+interface ScreenshotCommandOptions {
+  port?: number
+  verbose?: boolean
+}
+
+const VALUE_FLAGS = new Set([
+  '--sim',
+  '--port',
+  '-p',
+  '--output',
+  '-o',
+  '--out',
+  '--plan',
+  '--app',
+  '--device',
+  '--org',
+  '--repo',
+  '--api-origin',
+  '--branch',
+  '--platform',
+  '--slides',
+  '--shell-origin',
+  '--timeout',
+  '--ids',
+  '--out-dir',
+])
+const SUBCOMMANDS = new Set(['capture', 'slides', 'appstore', 'layers'])
+
+function findSubcommand(args: string[]): { name: string; index: number } | null {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg.startsWith('-')) {
+      if (VALUE_FLAGS.has(arg)) i++
+      continue
+    }
+    return SUBCOMMANDS.has(arg) ? { name: arg, index: i } : null
+  }
+  return null
+}
+
+function removeAt(args: string[], index: number): string[] {
+  return [...args.slice(0, index), ...args.slice(index + 1)]
+}
+
+function stripSimFlag(args: string[]): string[] {
+  const out: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--sim') {
+      i++
+      continue
+    }
+    out.push(args[i])
+  }
+  return out
+}
+
+export async function runScreenshotCommand(
+  args: string[],
+  opts: ScreenshotCommandOptions,
+): Promise<number | void> {
+  const sub = findSubcommand(args)
+  if (!sub || sub.name === 'capture') {
+    await runScreenshot(sub ? removeAt(args, sub.index) : args, opts)
+    return
+  }
+
+  if (sub.name === 'slides') {
+    await runSlides(removeAt(args, sub.index), opts)
+    return
+  }
+
+  if (sub.name === 'layers') {
+    const { runScreenshotLayers } = await import('./screenshot-layers')
+    await runScreenshotLayers(removeAt(args, sub.index), opts)
+    return
+  }
+
+  const appstoreArgs = removeAt(args, sub.index)
+  const nested = findSubcommand(appstoreArgs)
+  if (nested?.name === 'capture') {
+    // repo-only tooling: screenshots-capture statically imports playwright-core,
+    // which the published CLI never ships (it's external in build-cli.ts). a
+    // static import here would put that bare import at the top of THIS chunk,
+    // so every published `sootsim screenshot` printed ERR_MODULE_NOT_FOUND —
+    // keep it a runtime dynamic import that only evaluates when capture runs.
+    try {
+      const { runScreenshotsCapture } = await import('./screenshots-capture')
+      return await runScreenshotsCapture(
+        stripSimFlag(removeAt(appstoreArgs, nested.index)),
+      )
+    } catch (err) {
+      if (err instanceof Error && 'code' in err && err.code === 'ERR_MODULE_NOT_FOUND') {
+        console.error(
+          'screenshot appstore capture is repo-only tooling — it needs the rnx workspace (playwright is not shipped with the published CLI).',
+        )
+        return 1
+      }
+      throw err
+    }
+  }
+  return runScreenshots(appstoreArgs, opts)
+}

package/cli/commands/screenshot-layers.ts

@@ -0,0 +1,143 @@
+// sootsim screenshot layers — engine-rendered layer isolation export.
+//
+// captures one screen as a stack the 3d stage can pull apart: `full.png` is
+// the normal frame, `base.png` re-renders the frame with the target subtrees
+// hidden (content and glass blur behind them are real, not inpainted), and
+// each `layer-<testID>.png` draws exactly that subtree alone on transparency
+// at its on-screen position. `manifest.json` records device metrics and the
+// logical rect of every layer.
+
+import { mkdirSync, writeFileSync } from 'fs'
+import { resolve } from 'path'
+import { devices } from 'sootsim-engine/settings'
+import { buildResolveRectEval, type SampleRect } from '../browser-evals'
+import { callInBridge, createBridgeFromParsed, parseBridgeCliArgs } from '../ws-bridge'
+import { inspectWaitReady, waitReadyReason } from './inspect/core'
+
+interface ScreenshotLayersOptions {
+  port?: number
+  verbose?: boolean
+}
+
+export async function runScreenshotLayers(
+  args: string[],
+  opts: ScreenshotLayersOptions,
+): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+sootsim screenshot layers — export a screen as engine-isolated layers
+
+usage:
+  sootsim screenshot layers --ids <testID,testID,...> [--out-dir <dir>]
+
+options:
+  --ids <list>       comma-separated testIDs of the subtrees to isolate
+  --out-dir <dir>    output directory (default: /tmp/sootsim-layers)
+
+output:
+  full.png           the normal frame
+  base.png           the frame re-rendered with every listed subtree hidden
+  layer-<id>.png     each subtree rendered alone on a transparent frame
+  manifest.json      device metrics + logical rect per layer
+`)
+    process.exit(0)
+  }
+
+  const idsArg = args.find((_, i) => args[i - 1] === '--ids')
+  if (!idsArg) {
+    console.error('  --ids is required (comma-separated testIDs)')
+    process.exit(1)
+  }
+  const testIds = idsArg
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+  if (testIds.length === 0) {
+    console.error('  --ids resolved to an empty list')
+    process.exit(1)
+  }
+  const outDirArg = args.find((_, i) => args[i - 1] === '--out-dir')
+  const outDir = resolve(process.cwd(), outDirArg ?? '/tmp/sootsim-layers')
+
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripValueFlags: ['--ids', '--out-dir'],
+  })
+  const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 45000 })
+  try {
+    const readiness = await inspectWaitReady(bridge, 90_000)
+    if (!readiness.ready) {
+      throw new Error(
+        `app not ready to capture after ${Math.round(readiness.elapsedMs / 1000)}s ` +
+          `(${waitReadyReason(readiness)})`,
+      )
+    }
+
+    const rects: Record<string, SampleRect> = {}
+    for (const testId of testIds) {
+      const node = await bridge.send({
+        type: 'evaluate',
+        code: buildResolveRectEval({ id: testId }),
+      })
+      if (!node) throw new Error(`no node with testID "${testId}"`)
+      rects[testId] = node as SampleRect
+    }
+
+    mkdirSync(outDir, { recursive: true })
+    const savePng = (name: string, dataUrl: unknown) => {
+      if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) {
+        throw new Error(`capture for ${name} returned no image data`)
+      }
+      const path = resolve(outDir, name)
+      writeFileSync(
+        path,
+        Buffer.from(dataUrl.slice('data:image/png;base64,'.length), 'base64'),
+      )
+      console.log(`  saved: ${path}`)
+    }
+
+    savePng('full.png', await bridge.send({ type: 'screenshot' }))
+    savePng(
+      'base.png',
+      await bridge.send({
+        type: 'screenshot',
+        captureFilter: { hideTestIds: testIds },
+      }),
+    )
+    for (const testId of testIds) {
+      // every other listed target hides inside this solo, so nested targets
+      // (a button inside a lifted card) land in exactly one layer.
+      savePng(
+        `layer-${testId}.png`,
+        await bridge.send({
+          type: 'screenshot',
+          captureFilter: {
+            soloTestId: testId,
+            hideTestIds: testIds.filter((other) => other !== testId),
+          },
+        }),
+      )
+    }
+
+    const settings = (await callInBridge<Record<string, unknown> | null>(
+      bridge,
+      'SootSim.bridges.settings.get',
+    )) ?? { deviceModel: null }
+    const model =
+      typeof settings.deviceModel === 'string' && settings.deviceModel in devices
+        ? settings.deviceModel
+        : null
+    const device = model ? devices[model as keyof typeof devices] : null
+    const manifest = {
+      device: device
+        ? { model, width: device.width, height: device.height, scale: device.scale }
+        : { model },
+      layers: testIds.map((testId) => ({ testId, rect: rects[testId] })),
+    }
+    const manifestPath = resolve(outDir, 'manifest.json')
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+    console.log(`  saved: ${manifestPath}`)
+  } finally {
+    bridge.close()
+  }
+}

package/cli/commands/screenshot-mode.ts

@@ -0,0 +1,37 @@
+// sootsim mode screenshot — toggle the "screenshot mode" chrome overlay
+// in the running sootsim sim. orthogonal to `--no-shell` on the
+// `screenshot` command: this hides the DOM browser chrome (rail, menubar,
+// window controls) while still rendering the iOS shell inside the canvas.
+//
+// wraps the existing `toggle-screenshot-mode` shell action so the CLI
+// stays behavior-compatible with the menu item / keyboard shortcut.
+
+import { runShellBooleanMode, type ShellBooleanModeOptions } from './shell-boolean-mode'
+
+export async function runScreenshotMode(args: string[], opts: ShellBooleanModeOptions) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+rnxsim mode screenshot — toggle the screenshot-mode chrome overlay
+
+usage:
+  rnxsim mode screenshot [on|off|toggle]
+
+arguments:
+  on        enable screenshot mode (enables showFrame if needed)
+  off       disable screenshot mode
+  toggle    flip the current state (default)
+
+examples:
+  rnxsim mode screenshot
+  rnxsim mode screenshot on
+  rnxsim mode screenshot off
+`)
+    process.exit(0)
+  }
+
+  await runShellBooleanMode(args, opts, {
+    modeKey: 'screenshotMode',
+    displayName: 'screenshot-mode',
+    actionId: 'toggle-screenshot-mode',
+  })
+}