sootsim 0.1.83 → 0.1.85

package/src/dev-bundle-resolution.ts

@@ -0,0 +1,180 @@
+import { isLoopbackHost } from './backend-origin'
+import { METRO_BUNDLE_PATH, normalizeNativeDevBundleUrl } from './native-dev-bundle-url'
+
+export const DEFAULT_TEST_DRIVE_PORT = 8081
+
+export interface ResolvedDevBundle {
+  bundleUrl: string
+  port: number
+  framework: string
+  projectName?: string
+}
+
+function buildUnresolvedTargetError(targetLabel: string): Error {
+  return new Error(
+    `could not resolve a native bundle for ${targetLabel}. pass an explicit bundle URL or open Connect and choose the app there.`,
+  )
+}
+
+export function inferManifestFramework(
+  launchUrl: string | undefined,
+  sdkVersion: unknown,
+): string {
+  if (launchUrl?.includes('/one/metro-entry.bundle')) return 'one'
+  if (typeof sdkVersion === 'string' && sdkVersion) return 'expo'
+  return 'unknown'
+}
+
+function buildBaseUrl(protocol: string, host: string, port: number) {
+  return `${protocol}//${host}:${port}`
+}
+
+function shouldProxyLoopbackProbe(targetUrl: string) {
+  if (typeof window === 'undefined') return false
+  try {
+    const parsed = new URL(targetUrl)
+    return (
+      isLoopbackHost(parsed.hostname) &&
+      isLoopbackHost(window.location.hostname) &&
+      parsed.origin !== window.location.origin
+    )
+  } catch {
+    return false
+  }
+}
+
+async function fetchDevProbe(targetUrl: string, init?: RequestInit): Promise<Response> {
+  const requestInit: RequestInit = {
+    ...init,
+    cache: init?.cache ?? 'no-store',
+  }
+  if (!shouldProxyLoopbackProbe(targetUrl)) {
+    return fetch(targetUrl, requestInit)
+  }
+  return fetch(`/__fetch-proxy?url=${encodeURIComponent(targetUrl)}`, requestInit)
+}
+
+function getDefaultPortForProtocol(protocol: string) {
+  return protocol === 'https:' ? 443 : 80
+}
+
+function isBaseServerUrl(url: URL) {
+  const path = url.pathname || '/'
+  return (path === '/' || path === '') && !url.search && !url.hash
+}
+
+async function probeBaseUrlBundle(
+  baseUrl: string,
+  port: number,
+): Promise<ResolvedDevBundle | null> {
+  const normalizedBaseUrl = baseUrl.replace(/\/+$/, '')
+
+  try {
+    const manifestRes = await fetchDevProbe(`${normalizedBaseUrl}/`, {
+      headers: { 'expo-platform': 'ios' },
+    })
+    if (manifestRes.ok) {
+      const manifest = await manifestRes.json()
+      const client = manifest?.extra?.expoClient || manifest?.extra || {}
+      const launchUrl =
+        typeof manifest?.launchAsset?.url === 'string'
+          ? manifest.launchAsset.url
+          : undefined
+      if (launchUrl || client.name) {
+        return {
+          bundleUrl: normalizeNativeDevBundleUrl(
+            launchUrl || `${normalizedBaseUrl}${METRO_BUNDLE_PATH}`,
+          ),
+          port,
+          framework: inferManifestFramework(launchUrl, client.sdkVersion),
+          projectName: client.name,
+        }
+      }
+    }
+  } catch {}
+
+  // vanilla Metro (or any non-Expo dev server) — packager-status:running on
+  // /status is the canonical signature. we previously also did `HEAD
+  // /node_modules/one/metro-entry.bundle` as a framework discriminator, but
+  // Metro lazy-resolves modules at request time, so HEAD on *any* `.bundle`
+  // path can return 200 even when the underlying file doesn't exist. that
+  // caused false-positive One framework detection on non-One apps that had
+  // `node_modules/one` anywhere on disk (or that returned 200 HEAD + 404
+  // GET for missing bundles), surfacing as
+  //   "failed to fetch bundle (404|502): .../node_modules/one/metro-entry.bundle…"
+  // the Expo manifest probe above already returns the correct launchAsset.url
+  // for One apps (which serve the Expo manifest format via vxrn), so we
+  // drop the bespoke One probe entirely.
+  try {
+    const statusRes = await fetchDevProbe(`${normalizedBaseUrl}/status`)
+    if (statusRes.ok) {
+      const text = await statusRes.text()
+      if (text.includes('packager-status:running')) {
+        return {
+          bundleUrl: `${normalizedBaseUrl}${METRO_BUNDLE_PATH}`,
+          port,
+          framework: 'metro',
+        }
+      }
+    }
+  } catch {}
+
+  return null
+}
+
+export async function probePortBundle(port: number): Promise<ResolvedDevBundle | null> {
+  return probeBaseUrlBundle(buildBaseUrl('http:', 'localhost', port), port)
+}
+
+export async function resolveConnectionInput(input: string): Promise<ResolvedDevBundle> {
+  const trimmed = input.trim()
+
+  if (/^\d+$/.test(trimmed)) {
+    const port = parseInt(trimmed, 10)
+    const resolved = await probePortBundle(port)
+    if (resolved) return resolved
+    // soot's demo launcher allocates ports via `preferredPort` + shift if the
+    // preferred port is in use, so a flow YAML that hardcodes `app: 8081`
+    // breaks the day someone else binds 8081 first. probe a small window of
+    // higher ports for a metro server before giving up. only the *first* hit
+    // is used — we never scan past 3 to keep the search bounded and avoid
+    // grabbing a completely unrelated dev server.
+    const SHIFT_WINDOW = 3
+    for (let offset = 1; offset <= SHIFT_WINDOW; offset++) {
+      const shifted = await probePortBundle(port + offset)
+      if (shifted) return shifted
+    }
+    throw buildUnresolvedTargetError(
+      `localhost:${port} (also scanned +1..+${SHIFT_WINDOW})`,
+    )
+  }
+
+  const bundleUrl = trimmed.startsWith('http') ? trimmed : `http://${trimmed}`
+  let parsed: URL
+
+  try {
+    parsed = new URL(bundleUrl)
+  } catch {
+    throw new Error(
+      `could not parse "${input}". pass a dev-server port, a dev-server base URL, or a full bundle URL.`,
+    )
+  }
+
+  const protocol = parsed.protocol || 'http:'
+  const port = parsed.port
+    ? parseInt(parsed.port, 10)
+    : getDefaultPortForProtocol(protocol)
+  const baseUrl = buildBaseUrl(protocol, parsed.hostname, port)
+
+  // a bare base URL (just an origin, no path) is unambiguously a dev server
+  // to probe — regardless of host. probe its live manifest rather than
+  // guessing that the origin itself is the bundle URL. loopback vs. remote
+  // only affects how the probe fetch is routed (see shouldProxyLoopbackProbe).
+  if (isBaseServerUrl(parsed)) {
+    const resolved = await probeBaseUrlBundle(baseUrl, port)
+    if (resolved) return resolved
+    throw buildUnresolvedTargetError(baseUrl)
+  }
+
+  return { bundleUrl: parsed.toString(), port, framework: 'unknown' }
+}

package/src/home-paths.ts

@@ -0,0 +1,382 @@
+// canonical filesystem layout under ~/.sootsim/. shared by the CLI and the
+// electron main process so every surface agrees where runtimes, the daemon
+// lockfile, and caches live.
+//
+//   ~/.sootsim/
+//   ├── runtimes/
+//   │   ├── <version>/     unpacked dist/ of sootsim-engine
+//   │   └── active         text file with the active version string (win-safe
+//   │                      alternative to a symlink)
+//   ├── electron/
+//   │   └── <version>/     pinned electron binary (future: playwright-style)
+//   ├── profiles/
+//   │   └── profiles.json  storage profile metadata
+//   ├── cache/
+//   │   └── sootsim-runtime-<version>.tar.gz
+//   ├── daemon.json        lockfile: pid, ports, active runtime, heartbeat
+//   └── config.json        user prefs: update channel, cdn origin override
+
+import fs from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+export const SOOTSIM_HOME_ENV = 'SOOTSIM_HOME'
+export const ACTIVE_RUNTIME_FILE = 'active'
+export const DAEMON_LOCKFILE = 'daemon.json'
+export const CONFIG_FILE = 'config.json'
+export const DAEMON_HEARTBEAT_STALE_MS = 30_000
+
+export function sootsimHomeDir(): string {
+  const override = process.env[SOOTSIM_HOME_ENV]
+  if (override && override.length > 0) return path.resolve(override)
+  return path.join(homedir(), '.sootsim')
+}
+
+// detect when sootsim is running from a source checkout (the soot monorepo)
+// rather than a published npm install. used to skip auto-install of the
+// persistent launchd / systemd agent: dev shells shouldn't register an agent
+// whose Program path points at workspace artifacts that change between
+// sessions, and whose served engine assets are the stale prod build instead
+// of the live `bun dev:sootsim` output.
+//
+// overrides:
+//   SOOTSIM_DEV=1 / SOOTSIM_DEV=0           force the answer
+//   SOOTSIM_FORCE_DAEMON_INSTALL=1          pretend prod even from a dev
+//                                           checkout, for exercising the
+//                                           install path from this repo
+//
+// signal: realpath of process.argv[1] lands inside a `packages/sootsim/`
+// directory. workspace bin symlinks (`node_modules/.bin/sootsim` →
+// `packages/sootsim/dist-cli/bin.js`) and bun-direct invocations
+// (`bun packages/sootsim/cli/bin.ts ...`) both match; published installs
+// resolve under `node_modules/sootsim/` instead.
+export function isSootsimDevCheckout(): boolean {
+  if (process.env.SOOTSIM_FORCE_DAEMON_INSTALL === '1') return false
+  const env = process.env.SOOTSIM_DEV
+  if (env === '1' || env === 'true') return true
+  if (env === '0' || env === 'false') return false
+  const argv1 = process.argv[1]
+  if (!argv1) return false
+  try {
+    const real = fs.realpathSync(argv1)
+    return real.includes(`${path.sep}packages${path.sep}sootsim${path.sep}`)
+  } catch {
+    return false
+  }
+}
+
+export function runtimesDir(): string {
+  return path.join(sootsimHomeDir(), 'runtimes')
+}
+
+export function runtimeDir(version: string): string {
+  return path.join(runtimesDir(), version)
+}
+
+export function activeRuntimeFile(): string {
+  return path.join(runtimesDir(), ACTIVE_RUNTIME_FILE)
+}
+
+export function electronDir(): string {
+  return path.join(sootsimHomeDir(), 'electron')
+}
+
+export function electronUserDataDir(): string {
+  return path.join(electronDir(), 'userData')
+}
+
+export function electronVersionDir(version: string): string {
+  return path.join(electronDir(), version)
+}
+
+export function profilesDir(): string {
+  return path.join(sootsimHomeDir(), 'profiles')
+}
+
+// the launchd-managed daemon spawns ProgramArguments[0] directly, and macOS
+// Background Task Management attributes the entry to whoever code-signed
+// that binary. pointing launchd at bun directly makes Login Items say
+// "software from Jarred Sumner" (bun's signer); wrapping the invocation in
+// an ad-hoc-signed .app bundle here gives BTM a CFBundleDisplayName to
+// read instead.
+export function daemonAppDir(): string {
+  return path.join(sootsimHomeDir(), 'daemon-app')
+}
+
+export function daemonAppBundlePath(): string {
+  return path.join(daemonAppDir(), 'SootSim Daemon.app')
+}
+
+export function daemonAppLauncherPath(): string {
+  return path.join(daemonAppBundlePath(), 'Contents', 'MacOS', 'sootsim-daemon')
+}
+
+export function cacheDir(): string {
+  return path.join(sootsimHomeDir(), 'cache')
+}
+
+export function daemonLockfilePath(): string {
+  return path.join(sootsimHomeDir(), DAEMON_LOCKFILE)
+}
+
+export function configFilePath(): string {
+  return path.join(sootsimHomeDir(), CONFIG_FILE)
+}
+
+// --- shared sootsim config -----------------------------------------------
+//
+// ~/.sootsim/config.json is the single user-level config file every sootsim
+// surface (cli, electron renderer, dev browser via electron ipc) agrees on.
+//
+//   {
+//     "telemetry": true,                 // splash checkbox; cli + electron
+//     "settings": {                      // engine settings persisted across
+//       "onboardingComplete": true,      // sessions. shape mirrors the
+//       "betaConsentVersion": 1,         // PERSISTED_KEYS slice of
+//       "detailedTelemetry": false,      // SettingsValues — see
+//       ...                              // sootsim-engine/settings/schema.ts
+//     }
+//   }
+//
+// telemetry default is opt-in (missing/corrupt config means "enabled") so a
+// fresh install never silently drops error reports. settings default is empty
+// (the engine's getDefaults() fills the rest).
+
+export interface SharedConfig {
+  telemetry?: boolean
+  settings?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export function readSharedConfig(): SharedConfig {
+  try {
+    const raw = fs.readFileSync(configFilePath(), 'utf8')
+    const parsed = JSON.parse(raw) as SharedConfig
+    return parsed && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/** merge `patch` into the shared config and atomically write to disk. nested
+ *  objects (currently just `settings`) are shallow-merged so partial writes
+ *  don't clobber unrelated fields. returns the new full snapshot. */
+export function writeSharedConfig(patch: Partial<SharedConfig>): SharedConfig {
+  ensureSootsimHome()
+  const current = readSharedConfig()
+  const next: SharedConfig = { ...current, ...patch }
+  if (patch.settings && typeof patch.settings === 'object') {
+    next.settings = {
+      ...(current.settings && typeof current.settings === 'object'
+        ? current.settings
+        : {}),
+      ...patch.settings,
+    }
+  }
+  const tmp = `${configFilePath()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+  fs.renameSync(tmp, configFilePath())
+  return next
+}
+
+export function readTelemetryEnabled(): boolean {
+  return readSharedConfig().telemetry !== false
+}
+
+export function writeTelemetryEnabled(enabled: boolean): void {
+  writeSharedConfig({ telemetry: enabled })
+}
+
+export function ensureSootsimHome(): void {
+  fs.mkdirSync(sootsimHomeDir(), { recursive: true })
+  fs.mkdirSync(runtimesDir(), { recursive: true })
+  fs.mkdirSync(electronDir(), { recursive: true })
+  fs.mkdirSync(profilesDir(), { recursive: true })
+  fs.mkdirSync(cacheDir(), { recursive: true })
+}
+
+/** read the active runtime version string, or null if none is selected. */
+export function readActiveRuntime(): string | null {
+  try {
+    const value = fs.readFileSync(activeRuntimeFile(), 'utf8').trim()
+    return value.length > 0 ? value : null
+  } catch {
+    return null
+  }
+}
+
+/** set the active runtime version. caller is responsible for verifying the
+ *  version actually exists on disk before calling. */
+export function writeActiveRuntime(version: string): void {
+  fs.mkdirSync(runtimesDir(), { recursive: true })
+  fs.writeFileSync(activeRuntimeFile(), `${version}\n`, 'utf8')
+}
+
+/** list installed runtime versions (directories under runtimes/). sorted
+ *  ascending by semver when parseable, falling back to lexicographic for
+ *  odd names. */
+export function listInstalledRuntimes(): string[] {
+  try {
+    return fs
+      .readdirSync(runtimesDir(), { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort(compareSemver)
+  } catch {
+    return []
+  }
+}
+
+/** compare two version strings as coarse semver. treats pre-release
+ *  tags as lower than release of the same major.minor.patch. callers
+ *  that need strict semver compliance should use a dedicated library. */
+export function compareSemver(a: string, b: string): number {
+  const parse = (v: string): [number[], string] => {
+    const hyphen = v.indexOf('-')
+    const core = hyphen >= 0 ? v.slice(0, hyphen) : v
+    const pre = hyphen >= 0 ? v.slice(hyphen + 1) : ''
+    const parts = core.split('.').map((n) => Number.parseInt(n, 10))
+    if (parts.some((n) => !Number.isFinite(n))) return [[Number.POSITIVE_INFINITY], v]
+    return [parts, pre]
+  }
+  const [an, ap] = parse(a)
+  const [bn, bp] = parse(b)
+  for (let i = 0; i < Math.max(an.length, bn.length); i++) {
+    const av = an[i] ?? 0
+    const bv = bn[i] ?? 0
+    if (av !== bv) return av - bv
+  }
+  // pre-release of same core sorts lower than release (empty pre).
+  if (ap === bp) return 0
+  if (!ap) return 1
+  if (!bp) return -1
+  return ap < bp ? -1 : 1
+}
+
+/** absolute path to the active runtime's directory, or null if none active
+ *  or the active version is no longer installed. */
+export function activeRuntimeDir(): string | null {
+  const version = readActiveRuntime()
+  if (!version) return null
+  const dir = runtimeDir(version)
+  try {
+    if (fs.statSync(dir).isDirectory()) return dir
+  } catch {}
+  return null
+}
+
+// --- daemon lockfile ----------------------------------------------------
+
+export interface DaemonLockfile {
+  /** sootsim cli/daemon version that wrote the lockfile. bumped whenever
+   *  the lockfile shape changes so readers can gate on it. */
+  schema: 1
+  pid: number
+  /** platform — useful when one home dir is shared across platforms via NFS. */
+  platform: NodeJS.Platform
+  /** ws bridge port (where cli + electron open control connections). */
+  bridgePort: number
+  /** http runtime server port (where electron loads the renderer from). */
+  runtimePort: number
+  /** active runtime version at boot, or null if the daemon booted with no
+   *  runtime installed. updated live when the user runs `sootsim runtime use`. */
+  activeRuntime: string | null
+  /** absolute path to the active runtime's dist directory, or null. */
+  activeRuntimeDir: string | null
+  /** epoch-ms of daemon start. */
+  startedAt: number
+  /** epoch-ms of last heartbeat. daemons update this every ~5s; readers
+   *  treat the lockfile as stale if now - heartbeatAt > DAEMON_HEARTBEAT_STALE_MS. */
+  heartbeatAt: number
+  /** true while the daemon is still fetching/activating its runtime on first
+   *  boot. clients (electron splash, cli) should wait for this to become
+   *  false before treating the daemon as ready to serve. */
+  bootstrapping?: boolean
+}
+
+const DAEMON_LOCKFILE_MAX_BYTES = 16 * 1024
+
+export function readDaemonLockfile(): DaemonLockfile | null {
+  try {
+    // cap the read so a junk/large file on the lockfile path can't OOM
+    // the CLI when someone has been messing with ~/.sootsim/.
+    const fd = fs.openSync(daemonLockfilePath(), 'r')
+    try {
+      const buf = Buffer.alloc(DAEMON_LOCKFILE_MAX_BYTES)
+      const bytesRead = fs.readSync(fd, buf, 0, DAEMON_LOCKFILE_MAX_BYTES, 0)
+      const raw = buf.subarray(0, bytesRead).toString('utf8')
+      const parsed = JSON.parse(raw) as Partial<DaemonLockfile>
+      if (
+        parsed &&
+        parsed.schema === 1 &&
+        typeof parsed.pid === 'number' &&
+        typeof parsed.bridgePort === 'number' &&
+        typeof parsed.runtimePort === 'number' &&
+        typeof parsed.startedAt === 'number' &&
+        typeof parsed.heartbeatAt === 'number'
+      ) {
+        return parsed as DaemonLockfile
+      }
+      return null
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch {
+    return null
+  }
+}
+
+/** true when the lockfile exists, the named pid is alive, and the heartbeat
+ *  is recent. callers should reach for this before trusting any of the
+ *  ports inside.
+ *
+ *  pid-reuse note: `process.kill(pid, 0)` only checks that *some* process
+ *  with that pid exists. after a reboot or heavy fork churn the OS can
+ *  recycle the pid onto an unrelated process owned by the same user. the
+ *  heartbeat freshness check catches most of that (30s stale ⇒ reject),
+ *  but a stale lockfile where pid happens to be reused < 30s ago could
+ *  still slip through. the consumer paths that actually connect (electron
+ *  + ws-bridge client) time out quickly, so a stale lockfile degrades to
+ *  "connect attempt fails" rather than corrupt state. */
+export function isDaemonLockfileFresh(
+  lock: DaemonLockfile | null,
+  now = Date.now(),
+): lock is DaemonLockfile {
+  if (!lock) return false
+  if (now - lock.heartbeatAt > DAEMON_HEARTBEAT_STALE_MS) return false
+  try {
+    // signal 0 just tests whether the pid exists + we have perm to signal.
+    process.kill(lock.pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function writeDaemonLockfile(data: DaemonLockfile): void {
+  ensureSootsimHome()
+  const tmp = `${daemonLockfilePath()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+  fs.renameSync(tmp, daemonLockfilePath())
+}
+
+/** try to claim the lockfile atomically on daemon boot. returns true if
+ *  we now own it. returns false when another fresh daemon beat us to the
+ *  punch — callers should refuse to start. a stale lockfile (dead pid or
+ *  old heartbeat) is overwritten. race-safe: the final fs.renameSync is
+ *  atomic on POSIX and on NTFS. */
+export function claimDaemonLockfile(data: DaemonLockfile): boolean {
+  ensureSootsimHome()
+  const existing = readDaemonLockfile()
+  if (existing && isDaemonLockfileFresh(existing) && existing.pid !== data.pid) {
+    return false
+  }
+  writeDaemonLockfile(data)
+  return true
+}
+
+export function removeDaemonLockfile(): void {
+  try {
+    fs.unlinkSync(daemonLockfilePath())
+  } catch {}
+}