rnxsim 0.1.313 → 0.1.314

package/cli/parent-pid.ts

@@ -0,0 +1,204 @@
+import { execFileSync } from 'child_process'
+import { readFileSync } from 'fs'
+import { createRequire } from 'module'
+
+// look up a process's parent pid. returns null if we can't read it
+// (unsupported platform, process gone, permission denied).
+//
+// used by session-identity to walk one hop up from `process.ppid` — in a
+// Claude Code Bash tool the shell's parent is the agent-level process,
+// which is stable across invocations and distinct between agents.
+
+type Lookup = (pid: number) => number | null
+type CommLookup = (pid: number) => string | null
+
+let cached: Lookup | null = null
+let cachedComm: CommLookup | null = null
+
+export function getParentPid(pid: number): number | null {
+  if (!cached) cached = build()
+  try {
+    return cached(pid)
+  } catch {
+    return null
+  }
+}
+
+// short command name (comm) for a pid, or null when unreadable. used by the
+// owner-pid walk to stop at effectively-immortal session hosts (tmux/screen
+// servers and the Team Machine daemon), which must never become a sim owner.
+export function getProcessComm(pid: number): string | null {
+  if (!cachedComm) cachedComm = buildComm()
+  try {
+    return cachedComm(pid)
+  } catch {
+    return null
+  }
+}
+
+function buildComm(): CommLookup {
+  if (process.platform === 'linux') {
+    return (pid) => {
+      try {
+        return readFileSync(`/proc/${pid}/comm`, 'utf8').trim() || null
+      } catch {
+        return null
+      }
+    }
+  }
+  if (process.platform === 'darwin') {
+    const ffi = tryBuildDarwinCommFfi()
+    if (ffi) return ffi
+    return (pid) => readProcessTable().get(pid)?.comm || null
+  }
+  return () => null
+}
+
+function build(): Lookup {
+  // on any platform, if the shell exports $PPID and it differs from the
+  // node-level process.ppid, it's the shell's own parent — one level up
+  // from where we need to be. this is the cheapest and most portable
+  // grand-ppid source since it needs no subprocess or FFI.
+  const envPpid = Number(process.env.PPID)
+  if (Number.isFinite(envPpid) && envPpid > 1 && envPpid !== process.ppid) {
+    return () => envPpid
+  }
+
+  if (process.platform === 'linux') return buildLinux()
+  if (process.platform === 'darwin') {
+    // on Bun: libproc via FFI is ~0.8µs/call. on Node: one `ps` snapshot of
+    // the whole tree (see readProcessTable).
+    const ffi = tryBuildDarwinFfi()
+    if (ffi) return ffi
+    return (pid) => {
+      const ppid = readProcessTable().get(pid)?.ppid
+      return ppid !== undefined && ppid > 0 ? ppid : null
+    }
+  }
+  return () => null
+}
+
+// one snapshot of the whole process tree, shared by the ppid and comm lookups.
+// macOS has no /proc and Node cannot call libproc, so each lookup used to shell
+// out to `lsof -R -p <pid>` with a 2000ms budget — measured at 3.5s, 7.1s and
+// 7.9s on a loaded box, so every hop of an ancestor walk timed out, the walk
+// resolved to null, and `contrast ide open` launched a browser host with an
+// empty owner pid that `ide close` could never attribute. `ps -eo pid,ppid,comm`
+// answers for every process at once in ~0.1-0.9s. the short TTL keeps one walk
+// on one snapshot while a long-lived caller still sees the tree change.
+const PROCESS_TABLE_TTL_MS = 2000
+let processTable: { readAt: number; rows: Map<number, { ppid: number; comm: string }> } =
+  { readAt: 0, rows: new Map() }
+
+function readProcessTable(): Map<number, { ppid: number; comm: string }> {
+  const now = Date.now()
+  if (processTable.readAt && now - processTable.readAt < PROCESS_TABLE_TTL_MS) {
+    return processTable.rows
+  }
+  const rows = new Map<number, { ppid: number; comm: string }>()
+  try {
+    const out = execFileSync('ps', ['-eo', 'pid=,ppid=,comm='], {
+      encoding: 'utf8',
+      timeout: 5000,
+      maxBuffer: 8 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    for (const line of out.split('\n')) {
+      const parsed = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/)
+      if (!parsed) continue
+      // libproc reports pbi_comm — the executable's basename, truncated to
+      // MAXCOMLEN — and the immortal-host patterns are written against that
+      // shape, while `ps -o comm` prints the full path. normalize to one.
+      rows.set(Number(parsed[1]), {
+        ppid: Number(parsed[2]),
+        comm: (parsed[3].split('/').at(-1) ?? '').slice(0, PBI_COMM_LEN),
+      })
+    }
+  } catch {
+    // an unreadable table means unresolved ancestry, which callers already
+    // treat as "no defensible owner" and refuse on.
+  }
+  processTable = { readAt: now, rows }
+  return rows
+}
+
+function buildLinux(): Lookup {
+  return (pid) => {
+    try {
+      const raw = readFileSync(`/proc/${pid}/stat`, 'utf8')
+      const end = raw.lastIndexOf(')')
+      if (end < 0) return null
+      const rest = raw
+        .slice(end + 1)
+        .trim()
+        .split(/\s+/)
+      const ppid = Number(rest[1])
+      return Number.isFinite(ppid) && ppid > 0 ? ppid : null
+    } catch {
+      return null
+    }
+  }
+}
+
+// PROC_PIDTBSDINFO flavor for proc_pidinfo. struct proc_bsdinfo is 216 bytes;
+// pbi_ppid is at offset 16 (after pbi_flags, pbi_status, pbi_xstatus, pbi_pid,
+// each 4 bytes). source: <sys/proc_info.h> in the macOS SDK.
+const PROC_PIDTBSDINFO = 3
+const PROC_BSDINFO_SIZE = 216
+const PBI_PPID_OFFSET = 16
+// char pbi_comm[MAXCOMLEN] — after the 4-byte flags/status/xstatus/pid/ppid/
+// uid/gid/ruid/rgid/svuid/svgid/rfu_1 fields. source: <sys/proc_info.h>.
+const PBI_COMM_OFFSET = 48
+const PBI_COMM_LEN = 16
+
+function tryBuildDarwinFfi(): Lookup | null {
+  if (!process.versions?.bun) return null
+  try {
+    const r = createRequire(import.meta.url)
+    const { dlopen, FFIType } = r('bun:ffi')
+    const lib = dlopen('/usr/lib/libproc.dylib', {
+      proc_pidinfo: {
+        args: [FFIType.i32, FFIType.i32, FFIType.u64, FFIType.ptr, FFIType.i32],
+        returns: FFIType.i32,
+      },
+    })
+    const buf = Buffer.alloc(PROC_BSDINFO_SIZE)
+    return (pid) => {
+      const ret = Number(
+        lib.symbols.proc_pidinfo(pid, PROC_PIDTBSDINFO, 0n, buf, PROC_BSDINFO_SIZE),
+      )
+      if (ret <= 0) return null
+      const ppid = buf.readUInt32LE(PBI_PPID_OFFSET)
+      return ppid > 0 ? ppid : null
+    }
+  } catch {
+    return null
+  }
+}
+
+function tryBuildDarwinCommFfi(): CommLookup | null {
+  if (!process.versions?.bun) return null
+  try {
+    const r = createRequire(import.meta.url)
+    const { dlopen, FFIType } = r('bun:ffi')
+    const lib = dlopen('/usr/lib/libproc.dylib', {
+      proc_pidinfo: {
+        args: [FFIType.i32, FFIType.i32, FFIType.u64, FFIType.ptr, FFIType.i32],
+        returns: FFIType.i32,
+      },
+    })
+    const buf = Buffer.alloc(PROC_BSDINFO_SIZE)
+    return (pid) => {
+      const ret = Number(
+        lib.symbols.proc_pidinfo(pid, PROC_PIDTBSDINFO, 0n, buf, PROC_BSDINFO_SIZE),
+      )
+      if (ret <= 0) return null
+      const raw = buf.subarray(PBI_COMM_OFFSET, PBI_COMM_OFFSET + PBI_COMM_LEN)
+      const end = raw.indexOf(0)
+      const comm = raw.subarray(0, end < 0 ? raw.length : end).toString('utf8')
+      return comm || null
+    }
+  } catch {
+    return null
+  }
+}

package/cli/parse-args.ts

@@ -0,0 +1,211 @@
+// shared CLI argument parser — handles global flags, commands, and per-command flags
+
+export interface ParsedArgs {
+  command: string | null
+  commandArgs: string[]
+  globalFlags: Record<string, string | boolean | number>
+  help: boolean
+  version: boolean
+  verbose: boolean
+}
+
+const GLOBAL_FLAGS: Record<
+  string,
+  { type: 'string' | 'boolean' | 'number'; short?: string }
+> = {
+  '--help': { type: 'boolean', short: '-h' },
+  '--version': { type: 'boolean', short: '-V' },
+  '--verbose': { type: 'boolean', short: '-v' },
+  '--port': { type: 'number', short: '-p' },
+  '--device': { type: 'string', short: '-d' },
+  '--theme': { type: 'string', short: '-t' },
+  '--headless': { type: 'boolean' },
+  '--driver': { type: 'string' },
+  '--sim': { type: 'string' },
+  // documented aliases for --sim (CLAUDE.md / skills / engine docs say
+  // `--session <id>`). normalized to the sim target in bin.ts.
+  '--session': { type: 'string' },
+  '--tab': { type: 'string' },
+}
+
+// top-level verbs that route into runInspect. the surface is intentionally
+// tiny — everything else lives under one of the grouping verbs:
+//   - `sootsim get <noun>`        reads
+//   - `sootsim do <action>`       writes
+//   - `sootsim debug <tool>`      instrumentation (handled by runDebug)
+//   - `sootsim inspect <sub>`     full legacy surface, all subcommands
+// `describe` and `find` stay at root as the most common entrypoints.
+// `list` stays at root because it's a sim-management read.
+export const TOP_LEVEL_RUNTIME_COMMANDS = new Set([
+  'list',
+  'describe',
+  'find',
+  'get',
+  'do',
+  'wait',
+  'network',
+  'logs',
+  'shell',
+])
+
+// grouping verbs that take a sub-verb (`sootsim wait ready`,
+// `sootsim do tap-id`). agents and humans very often type the hyphenated
+// form (`sootsim wait-ready`, `sootsim do-tap-id`) — it reads as one
+// command and matches the typed-tool names (rnx_wait_ready). bin.ts
+// normalizes `<verb>-<rest>` → `<verb> <rest>` for these so the intuitive
+// spelling just works instead of failing as "unknown command".
+export const HYPHENATED_GROUPING_VERBS = new Set(['do', 'get', 'wait', 'shell', 'debug'])
+
+// known commands — if first positional arg matches, it's a command
+const COMMANDS = new Set([
+  'detox',
+  'maestro',
+  'record',
+  'film',
+  'storage',
+  'permissions',
+  'perf',
+  'screenshot',
+  'state',
+  'reset',
+  'camera',
+  'mode',
+  'inspect',
+  'debug',
+  'timeline',
+  'what-happened',
+  'shell',
+  'assert',
+  'device',
+  'open',
+  'list',
+  'use',
+  'claim',
+  'close',
+  'compat',
+  'report-issue',
+  'desktop',
+  'login',
+  'logout',
+  'auth',
+  'setup',
+  'serve',
+  'daemon',
+  'runtime',
+  'upgrade',
+  'update',
+  'version',
+  'skill',
+  'config',
+  'cleanup',
+  // stage config-plugin fonts into a build's asset manifest (run.sh build path)
+  'app-fonts',
+  // internal — not user-facing, spawned as a subprocess by electron main
+  // and by `sootsim agent start`.
+  'agent-wrapper',
+  // attached projects + local agent sessions.
+  'agent',
+  ...TOP_LEVEL_RUNTIME_COMMANDS,
+])
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const args = argv.slice(2)
+  const result: ParsedArgs = {
+    command: null,
+    commandArgs: [],
+    globalFlags: {},
+    help: false,
+    version: false,
+    verbose: false,
+  }
+
+  let i = 0
+
+  // parse global flags and detect command
+  while (i < args.length) {
+    const arg = args[i]
+
+    // explicit separator — strip it, everything after is command args
+    if (arg === '--') {
+      result.commandArgs.push(...args.slice(i + 1))
+      break
+    }
+
+    // check for global flag
+    const flagEntry = Object.entries(GLOBAL_FLAGS).find(
+      ([name, def]) => name === arg || def.short === arg,
+    )
+
+    if (flagEntry) {
+      const [name, def] = flagEntry
+      const key = name.replace(/^--/, '')
+      if (def.type === 'boolean') {
+        result.globalFlags[key] = true
+        i++
+      } else {
+        const val = args[i + 1]
+        if (val === undefined || val.startsWith('-')) {
+          // missing value — treat as error, pass through
+          console.error(`  warning: ${arg} requires a value`)
+          i++
+          continue
+        }
+        if (def.type === 'number') {
+          const num = Number(val)
+          if (Number.isNaN(num)) {
+            console.error(`  warning: ${arg} requires a number, got "${val}"`)
+            i += 2
+            continue
+          }
+          result.globalFlags[key] = num
+        } else {
+          result.globalFlags[key] = val
+        }
+        i += 2
+      }
+      continue
+    }
+
+    // first non-flag arg — is it a command?
+    if (!result.command && !arg.startsWith('-')) {
+      // hyphenated grouping-verb spelling (`wait-ready`, `do-tap-id`):
+      // agents and humans type it constantly (it reads as one command and
+      // mirrors the typed tool names). split only the FIRST hyphen so
+      // multi-segment sub-verbs survive (`do-tap-id` → `do` `tap-id`).
+      // without this it fell through to the unrecognized branch as
+      // "unknown command: wait-ready" with empty stdout.
+      const dash = arg.indexOf('-')
+      if (dash > 0) {
+        const verb = arg.slice(0, dash)
+        const sub = arg.slice(dash + 1)
+        if (HYPHENATED_GROUPING_VERBS.has(verb) && sub.length > 0) {
+          result.command = verb
+          const rest = args.slice(i + 1)
+          result.commandArgs = [sub, ...(rest[0] === '--' ? rest.slice(1) : rest)]
+          break
+        }
+      }
+      if (COMMANDS.has(arg)) {
+        result.command = arg
+        const rest = args.slice(i + 1)
+        // strip leading -- separator if present
+        result.commandArgs = rest[0] === '--' ? rest.slice(1) : rest
+        break
+      }
+      // not a recognized command — leave it as command args so bin.ts can
+      // print a focused unknown-command message.
+      result.commandArgs = args.slice(i)
+      break
+    }
+
+    // unrecognized flag — pass through to command
+    result.commandArgs.push(arg)
+    i++
+  }
+
+  result.help = !!result.globalFlags['help']
+  result.version = !!result.globalFlags['version']
+  result.verbose = !!result.globalFlags['verbose']
+
+  return result
+}

package/cli/prompt.ts

@@ -0,0 +1,51 @@
+// minimal readline prompts — no external dependencies
+
+import { createInterface } from 'readline'
+
+const rl = () =>
+  createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+
+function ask(question: string): Promise<string> {
+  return new Promise((resolve) => {
+    const r = rl()
+    r.question(question, (answer) => {
+      r.close()
+      resolve(answer.trim())
+    })
+  })
+}
+
+export async function confirm(message: string, defaultYes = true): Promise<boolean> {
+  const hint = defaultYes ? '[Y/n]' : '[y/N]'
+  // non-interactive stdin (piped, /dev/null, closed) — readline's question
+  // callback would never fire, leaving the await unsettled and the process
+  // exiting 0 with a `Detected unsettled top-level await` warning. degrade
+  // to the default instead so scripted invocations behave predictably.
+  if (!process.stdin.isTTY) {
+    console.log(`  ${message} ${hint} ${defaultYes ? 'y' : 'n'} (non-interactive)`)
+    return defaultYes
+  }
+  const answer = await ask(`  ${message} ${hint} `)
+  if (answer === '') return defaultYes
+  return answer.toLowerCase().startsWith('y')
+}
+
+export async function select(message: string, options: string[]): Promise<number> {
+  console.log(`\n  ${message}\n`)
+  for (let i = 0; i < options.length; i++) {
+    console.log(`    ${i + 1}. ${options[i]}`)
+  }
+  console.log()
+  // non-interactive stdin — pick the first option rather than hanging.
+  if (!process.stdin.isTTY) {
+    console.log(`  choose [1-${options.length}]: 1 (non-interactive)`)
+    return 0
+  }
+  const answer = await ask(`  choose [1-${options.length}]: `)
+  const num = parseInt(answer, 10)
+  if (num >= 1 && num <= options.length) return num - 1
+  return 0 // default to first
+}

package/cli/recording-access.ts

@@ -0,0 +1,107 @@
+import { readSharedDesktopAuthSession } from '../src/auth/shared-session'
+import { authHeaderValue, resolveCliAuth, type CliAuth } from './auth'
+import { resolveDefaultUploadOrigin } from './commands/upload'
+
+type BillingSubscriptionSnapshot = {
+  plan?: 'free' | 'personal' | 'team'
+  entitlements?: {
+    desktopRecording?: boolean
+  }
+}
+
+async function billingOriginFor(auth: CliAuth, originOverride?: string): Promise<string> {
+  // an explicit override (e.g. --preview-origin https://contrast.localhost:3000 from
+  // `maestro test --preview`) wins over whatever origin the shared auth session
+  // happens to remember. this keeps local preview-upload flows pointed
+  // at the local billing endpoint even when the desktop session token
+  // was last minted against contrast.
+  if (originOverride) return originOverride.replace(/\/$/, '')
+  if (auth.kind === 'session' && auth.origin) {
+    return auth.origin.replace(/\/$/, '')
+  }
+  const shared = readSharedDesktopAuthSession()
+  if (shared?.origin) {
+    return shared.origin.replace(/\/$/, '')
+  }
+  // api-key auth (RNX_API_KEY) carries no origin.
+  // resolve it the same way the upload itself does — probe a local Contrast
+  // stack on :3000, else fall back to prod. this keeps the entitlement
+  // check pointed at the *same* origin the recording will upload to (the
+  // engine resolves loopback sims to the local :3000 stack); checking prod
+  // billing with a key minted against the local stack would 401 here even
+  // though the upload would have succeeded.
+  return (await resolveDefaultUploadOrigin()).replace(/\/$/, '')
+}
+
+export interface RecordingEntitlementOptions {
+  /** override the origin used to check billing. when the CLI is running
+   *  against a local Contrast stack (e.g. `maestro test --preview --preview-origin
+   *  https://contrast.localhost:3000`), the recording entitlement needs to hit the
+   *  same origin that'll receive the upload — not the remote contrast
+   *  origin stored in the shared desktop session. */
+  originOverride?: string
+  /** allow GitHub installation/action auth to record for pr preview uploads.
+   *  this is intentionally opt-in so local `sootsim record` stays tied to
+   *  the user's paid/trial desktop entitlement. */
+  allowGitHubAuth?: boolean
+}
+
+export async function ensureCliRecordingEntitlement(
+  commandLabel: string,
+  opts: RecordingEntitlementOptions = {},
+): Promise<void> {
+  const auth = resolveCliAuth()
+  if (!auth) {
+    process.stderr.write(
+      `\n  rnx ${commandLabel} needs auth before it can check recording access.\n\n` +
+        `  pick one:\n` +
+        `    • run \`rnxsim login\`\n` +
+        `    • set RNX_API_KEY=sk_rnx_... (recommended for CI)\n\n`,
+    )
+    process.exit(1)
+  }
+
+  if (auth.kind === 'github' && opts.allowGitHubAuth) return
+
+  const billingOrigin = await billingOriginFor(auth, opts.originOverride)
+  let res: Response
+  try {
+    res = await fetch(`${billingOrigin}/api/sootsim/billing/subscription`, {
+      headers: { authorization: authHeaderValue(auth) },
+    })
+  } catch (error) {
+    process.stderr.write(
+      `\n  rnx ${commandLabel} couldn't verify recording access.\n` +
+        `  ${error instanceof Error ? error.message : String(error)}\n\n`,
+    )
+    process.exit(1)
+  }
+
+  if (res.status === 401) {
+    process.stderr.write(
+      `\n  rnx ${commandLabel} couldn't verify recording access with the current auth against ${billingOrigin}.\n` +
+        `  sign in again for that origin, or provide a valid RNX_API_KEY.\n\n`,
+    )
+    process.exit(1)
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '')
+    process.stderr.write(
+      `\n  rnx ${commandLabel} couldn't verify recording access (${res.status}).\n` +
+        `  ${text || 'unexpected billing response'}\n\n`,
+    )
+    process.exit(1)
+  }
+
+  const data = (await res.json()) as BillingSubscriptionSnapshot
+  if (data.entitlements?.desktopRecording === true) return
+
+  const plan = data.plan ?? 'free'
+  process.stderr.write(
+    `\n  rnx ${commandLabel} recording requires Personal, Team, or an active trial.\n` +
+      `  current plan: ${plan}.\n` +
+      `  free keeps basic 3d mode; the trial unlocks the full Personal surface.\n\n`,
+  )
+  process.exit(1)
+}

package/cli/registry.ts

@@ -0,0 +1 @@
+export * from '@sootsim/skills/cli'

package/cli/resolve-assets.ts

@@ -0,0 +1,63 @@
+// resolve sootsim's bundled assets (fonts, icons, sounds)
+// regardless of how the package was installed (source checkout, npm install, bunx).
+//
+// uses import.meta.url to derive the package root, then checks both
+// the source layout (public/) and npm-installed layout (public/).
+
+import { existsSync, readFileSync } from 'fs'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { rnxPublicBrand } from '../src/public-brand'
+
+// when bundled by esbuild, this file lives at dist-cli/bin.js
+// when running from source, this file lives at cli/resolve-assets.ts
+const thisDir = dirname(fileURLToPath(import.meta.url))
+
+// walk up to find package root: look for package.json with name "sootsim"
+function findPackageRoot(): string {
+  let dir = thisDir
+  for (let i = 0; i < 5; i++) {
+    try {
+      const pkgPath = resolve(dir, 'package.json')
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        if (pkg.name === rnxPublicBrand.packageName) return dir
+      }
+    } catch {}
+    dir = dirname(dir)
+  }
+  // fallback: assume one level up from this file
+  return dirname(thisDir)
+}
+
+const packageRoot = findPackageRoot()
+
+export interface SootSimAssets {
+  fontsDir: string
+  iconsDir: string
+  soundsDir: string
+  packageRoot: string
+}
+
+export function resolveAssets(): SootSimAssets {
+  // both source and npm-installed layouts use public/ at the package root
+  const publicDir = resolve(packageRoot, 'public')
+
+  const fontsDir = resolve(publicDir, 'fonts')
+  const iconsDir = resolve(publicDir, 'icons')
+  const soundsDir = resolve(publicDir, 'sounds')
+
+  if (!existsSync(fontsDir)) {
+    console.warn(`[rnx] warning: fonts directory not found at ${fontsDir}`)
+  }
+
+  return {
+    fontsDir,
+    iconsDir,
+    soundsDir,
+    packageRoot,
+  }
+}
+
+// re-export packageRoot for use in CLI commands that need SOOTSIM_ROOT
+export { packageRoot }