rnxsim 0.1.313 → 0.1.314

package/cli/commands/timeline.ts

@@ -0,0 +1,122 @@
+// sootsim timeline — control the semantic agent-facing event log
+//
+// `sootsim record` is for video/screen capture; `sootsim debug record` is
+// for the engine-internal debug-channel ring; this command is the third
+// surface and explicitly distinct: it manages SootSim.bridges.timeline,
+// the unified, agent-facing semantic event stream across host / shell
+// worker / tenant worker.
+//
+// usage:
+//   sootsim timeline status                      # what's enabled
+//   sootsim timeline start [kinds]               # enable kinds (default: opt-in defaults)
+//   sootsim timeline stop [kinds]                # disable kinds (or 'all')
+//   sootsim timeline clear                       # drop all events + cursors
+//   sootsim timeline dump <file>                 # write current ring to JSON
+//
+// see `sootsim what-happened` for the read side.
+
+import { writeFileSync } from 'fs'
+import { callInBridge, createBridgeFromParsed, parseBridgeCliArgs } from '../ws-bridge'
+
+interface TimelineOptions {
+  port?: number
+  verbose?: boolean
+}
+
+function printHelp() {
+  console.log(`
+rnxsim timeline — control the semantic event timeline
+
+usage:
+  rnxsim timeline <subcommand> [args]
+
+subcommands:
+  status                  show enabled kinds and ring sizes
+  start [kinds]           enable kinds (csv); 'all' for every opt-in
+  stop [kinds]            disable kinds (csv); 'all' for every kind
+  clear                   drop all events + cursors
+  dump <file>             write current merged ring to JSON
+
+note: cheap kinds (console, fetch, app-launch, keyboard, screen, alert,
+toast, notification, route, shell, actionsheet, picker) record at all times.
+start/stop enables opt-in kinds (react-commit, scroll, gesture, text-input,
+layout, reanimated, animation).
+
+read the timeline with: rnxsim what-happened
+`)
+}
+
+export async function runTimeline(args: string[], opts: TimelineOptions) {
+  const parsed = parseBridgeCliArgs(args, {
+    port: opts.port,
+    stripBooleanFlags: ['--json', '--help', '-h'],
+  })
+  const sub = parsed.positional[0]
+  if (!sub || args.includes('--help') || args.includes('-h')) {
+    printHelp()
+    process.exit(0)
+  }
+  const json = args.includes('--json')
+  const bridge = createBridgeFromParsed(parsed)
+
+  const rest = parsed.positional.slice(1)
+  const kinds = rest[0]
+    ? rest[0]
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : []
+
+  try {
+    switch (sub) {
+      case 'status': {
+        const status = await callInBridge(bridge, 'SootSim.bridges.timeline.status')
+        console.log(JSON.stringify(status, null, json ? 0 : 2))
+        break
+      }
+      case 'start':
+      case 'enable': {
+        if (kinds.length === 0) kinds.push('all')
+        await callInBridge(bridge, 'SootSim.bridges.timeline.enable', ...kinds)
+        const status = await callInBridge(bridge, 'SootSim.bridges.timeline.status')
+        console.log(JSON.stringify(status, null, json ? 0 : 2))
+        break
+      }
+      case 'stop':
+      case 'disable': {
+        if (kinds.length === 0) kinds.push('all')
+        await callInBridge(bridge, 'SootSim.bridges.timeline.disable', ...kinds)
+        const status = await callInBridge(bridge, 'SootSim.bridges.timeline.status')
+        console.log(JSON.stringify(status, null, json ? 0 : 2))
+        break
+      }
+      case 'clear': {
+        await callInBridge(bridge, 'SootSim.bridges.timeline.clear')
+        console.log('  cleared')
+        break
+      }
+      case 'dump': {
+        const outPath = rest[0]
+        if (!outPath) {
+          console.error('  usage: rnxsim timeline dump <file>')
+          process.exit(1)
+        }
+        const result = await callInBridge<{ events: unknown[] }>(
+          bridge,
+          'SootSim.bridges.timeline.recent',
+          { limit: 1_000_000 },
+        )
+        writeFileSync(outPath, JSON.stringify(result.events, null, 2) + '\n')
+        console.log(`  wrote ${result.events.length} event(s) to ${outPath}`)
+        break
+      }
+      default: {
+        console.error(`  unknown subcommand: ${sub}`)
+        printHelp()
+        process.exit(1)
+      }
+    }
+  } finally {
+    bridge.close()
+  }
+}

package/cli/commands/upgrade.ts

@@ -0,0 +1,208 @@
+// sootsim upgrade — one command to get current.
+//
+// the sootsim CLI (the `sootsim` npm package) and the engine runtime (the
+// versioned tarball served to the browser/electron shell) are versioned
+// independently. that split is a frequent source of "I ran upgrade but the
+// version didn't change" confusion — the user upgraded one half. this
+// command checks and updates both:
+//
+//   1. CLI     — query the npm registry; if behind, self-update the global
+//                install with the same package manager that installed it
+//                (bun/pnpm/npm, detected from the running binary's path).
+//                npx-cache runs can't self-update in place, so those get
+//                the exact command to run instead.
+//   2. runtime — delegate to `sootsim runtime install`, which resolves the
+//                channel's latest, downloads + verifies
+//                it, and activates.
+//
+// each half is a no-op when already current, so the command is safe to
+// run anytime.
+
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { compareSemver } from '@contrast/runtime-delivery'
+import { getCliVersion } from '../../src/cli-version'
+import {
+  isSootsimDevCheckout,
+  readActiveRuntime,
+  runtimeDir,
+  sootsimHomeDir,
+} from '../../src/home-paths'
+import { resolveSootSimAppConfig } from '../app-config'
+import { fetchRuntimeReleaseNotes, formatRuntimeReleaseNotes } from '../runtime-notes'
+import { runRuntime } from './runtime'
+
+const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/rnxsim/latest'
+
+export async function runUpgrade(args: string[]): Promise<void> {
+  // `--help` is handled upstream in bin.ts via the CLI registry (meta.ts) —
+  // it never reaches here.
+  const channelIdx = args.indexOf('--channel')
+  const channel =
+    channelIdx >= 0 && args[channelIdx + 1] ? args[channelIdx + 1] : undefined
+
+  console.log('rnxsim upgrade\n')
+
+  // --- 1. engine runtime --------------------------------------------------
+  // runtime first, CLI last: the CLI self-update replaces this process's
+  // own dist files on disk, and any dynamic import after the swap resolves
+  // against renamed chunk hashes and crashes (observed in a container run).
+  console.log('runtime:')
+  const beforeRuntime = readActiveRuntime()
+  const { config } = await resolveSootSimAppConfig()
+  const configuredRuntime = config?.runtimeVersion
+  const configuredRuntimeWasInstalled = configuredRuntime
+    ? fs.existsSync(path.join(runtimeDir(configuredRuntime), 'index.html'))
+    : false
+  if (configuredRuntime) {
+    console.log(`  project config: v${configuredRuntime}`)
+  }
+  const install =
+    configuredRuntime && configuredRuntimeWasInstalled
+      ? null
+      : await runRuntime(
+          [
+            'install',
+            ...(configuredRuntime ? [configuredRuntime, '--set-active=false'] : []),
+            ...(channel ? ['--channel', channel] : []),
+          ],
+          {},
+        )
+  const installedRuntime = install?.version ?? configuredRuntime ?? readActiveRuntime()
+  if (installedRuntime) {
+    console.log(
+      configuredRuntime
+        ? configuredRuntimeWasInstalled
+          ? `  result:  v${installedRuntime} already installed for this project`
+          : `  result:  not installed → v${installedRuntime} for this project`
+        : beforeRuntime && beforeRuntime !== installedRuntime
+          ? `  result:  v${beforeRuntime} → v${installedRuntime}`
+          : !beforeRuntime
+            ? `  result:  not installed → v${installedRuntime}`
+            : `  result:  v${installedRuntime} already current`,
+    )
+  }
+  const releaseNotes = installedRuntime
+    ? await fetchRuntimeReleaseNotes(installedRuntime)
+    : null
+
+  // --- 2. CLI npm package -------------------------------------------------
+  console.log('\ncli:')
+  await upgradeCli()
+
+  if (installedRuntime) {
+    console.log(`\n${formatRuntimeReleaseNotes(installedRuntime, releaseNotes)}`)
+  }
+}
+
+type CliInstallKind =
+  | { kind: 'dev' }
+  | { kind: 'npx' }
+  | { kind: 'global'; command: string; args: string[] }
+
+// how is this CLI process installed? keyed off the real path of the running
+// entry script — global installs land under each manager's global root,
+// npx/bunx runs land in their throwaway caches, and the Contrast monorepo dev
+// checkout runs from packages/sootsim.
+function detectCliInstall(): CliInstallKind {
+  if (isSootsimDevCheckout()) return { kind: 'dev' }
+  let real = process.argv[1] ?? ''
+  try {
+    real = fs.realpathSync(real)
+  } catch {}
+  const sep = path.sep
+  if (real.includes(`${sep}_npx${sep}`) || real.includes(`${sep}.bunx${sep}`)) {
+    return { kind: 'npx' }
+  }
+  if (real.includes(`${sep}.bun${sep}`)) {
+    return { kind: 'global', command: 'bun', args: ['add', '-g', 'rnxsim@latest'] }
+  }
+  if (real.includes(`${sep}pnpm${sep}`)) {
+    return { kind: 'global', command: 'pnpm', args: ['add', '-g', 'rnxsim@latest'] }
+  }
+  // the desktop splash installs the CLI into a user-writable prefix under the
+  // sootsim home (`~/.sootsim/cli`) to dodge the EACCES a plain `npm i -g` hits
+  // when npm's global prefix is a system-owned dir. self-update into that same
+  // prefix so upgrade doesn't fall back to the unwritable global prefix.
+  const cliPrefix = path.join(sootsimHomeDir(), 'cli')
+  if (real.startsWith(`${cliPrefix}${sep}`)) {
+    return {
+      kind: 'global',
+      command: 'npm',
+      args: ['i', '-g', '--prefix', cliPrefix, 'rnxsim@latest'],
+    }
+  }
+  const installerPrefix = path.resolve(
+    process.env.SOOTSIM_CLI_PREFIX || path.join(os.homedir(), '.local'),
+  )
+  if (real.startsWith(`${installerPrefix}${sep}`)) {
+    return {
+      kind: 'global',
+      command: 'npm',
+      args: ['i', '-g', '--prefix', installerPrefix, 'rnxsim@latest'],
+    }
+  }
+  return { kind: 'global', command: 'npm', args: ['i', '-g', 'rnxsim@latest'] }
+}
+
+async function upgradeCli(): Promise<void> {
+  const current = getCliVersion()
+  const latest = await fetchLatestCliVersion()
+
+  if (!latest) {
+    console.log(`  v${current} — couldn't reach the npm registry, skipped`)
+    return
+  }
+  if (compareSemver(latest, current) <= 0) {
+    console.log(`  v${current} (latest)`)
+    return
+  }
+
+  const install = detectCliInstall()
+  console.log(`  v${current} → v${latest}`)
+
+  if (install.kind === 'dev') {
+    console.log(`  running from the Contrast dev checkout — pull instead of upgrading`)
+    return
+  }
+  if (install.kind === 'npx') {
+    console.log(`  running from the npx cache — get the latest with:`)
+    console.log(`    npx rnxsim@latest`)
+    return
+  }
+
+  const printed = `${install.command} ${install.args.join(' ')}`
+  console.log(`  updating global install (${printed})…`)
+  const ok = await runInherit(install.command, install.args)
+  if (ok) {
+    console.log(`  updated to v${latest}`)
+  } else {
+    console.log(`  update failed — run it yourself:`)
+    console.log(`    ${printed}`)
+  }
+}
+
+function runInherit(command: string, args: string[]): Promise<boolean> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: 'inherit' })
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+}
+
+async function fetchLatestCliVersion(): Promise<string | null> {
+  try {
+    // cap the registry lookup so a hung npm registry can't stall upgrade.
+    const res = await fetch(REGISTRY_LATEST_URL, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(8000),
+    })
+    if (!res.ok) return null
+    const json = (await res.json()) as { version?: unknown }
+    return typeof json.version === 'string' && json.version ? json.version : null
+  } catch {
+    return null
+  }
+}