rnxsim 0.0.0 → 0.1.313

package/src/home-paths.ts

@@ -0,0 +1,552 @@
+// 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
+//   ├── dev-bridge.json    live Vite dev bridge pointer for local CLI commands
+//   ├── runtime-upgraded.json  one-shot notice written by the daemon's
+//   │                      background updater, consumed (printed + deleted)
+//   │                      by the next interactive CLI run
+//   ├── automatic-cleanup-v1.json  completion marker for the one-time safe
+//   │                      cleanup introduced for legacy unbounded data
+//   └── config.json        user prefs: update channel, cdn origin override,
+//                          telemetry, engine settings
+
+import { randomUUID } from 'node:crypto'
+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 DEV_BRIDGE_LOCKFILE = 'dev-bridge.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 Contrast 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
+  }
+}
+
+// detect the human's dev workstation by the env markers the developer sets in
+// their shell profile (`IS_TAMAGUI_DEV=1` in ~/.zshrc). distinct from
+// isSootsimDevCheckout, which keys on the *binary path*: a globally-installed
+// `sootsim` binary on the dev machine would NOT match the checkout path, yet a
+// persistent daemon registered there is just as dangerous. it runs in the
+// background carrying the workstation's dev env (dev auth tokens, prod-pointing
+// vars), and when the live `bun dev` stack already owns the bridge port it
+// silently lands on a fallback port and shadows the real one with stale assets
+// — the "I was on the daemon on port 7-something" footgun.
+//
+// override: SOOTSIM_FORCE_DAEMON_INSTALL=1 to run the daemon here anyway.
+export function isDevWorkstation(): boolean {
+  if (process.env.SOOTSIM_FORCE_DAEMON_INSTALL === '1') return false
+  return process.env.IS_TAMAGUI_DEV === '1'
+}
+
+// the persistent launchd / systemd daemon must never auto-install or run on a
+// dev checkout or a dev workstation. either makes the background agent point at
+// moving workspace artifacts / dev env and serve stale assets that shadow the
+// live dev stack. setup and the launchd-spawned `sootsim serve` boot consult
+// this; a foreground `sootsim serve` the dev starts
+// by hand is intentional and stays allowed.
+export function shouldSkipPersistentDaemon(): boolean {
+  return isSootsimDevCheckout() || isDevWorkstation()
+}
+
+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 devBridgeLockfilePath(): string {
+  return path.join(sootsimHomeDir(), DEV_BRIDGE_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.
+//
+// privacy preferences live in the nested settings object so the cli, desktop
+// main process, renderer, daemon-served browser, and settings UI all read and
+// write one persisted value per choice.
+
+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 interface PrivacyPreferences {
+  productAnalytics: boolean
+  crashReports: boolean
+  configured: boolean
+}
+
+export function readPrivacyPreferences(): PrivacyPreferences {
+  const settings = readSharedConfig().settings
+  const productAnalytics = settings?.productAnalytics
+  const crashReports = settings?.crashReports
+  return {
+    productAnalytics: typeof productAnalytics === 'boolean' ? productAnalytics : true,
+    crashReports: typeof crashReports === 'boolean' ? crashReports : true,
+    configured:
+      typeof productAnalytics === 'boolean' && typeof crashReports === 'boolean',
+  }
+}
+
+export function writePrivacyPreferences(
+  preferences: Pick<PrivacyPreferences, 'productAnalytics' | 'crashReports'>,
+): void {
+  writeSharedConfig({
+    settings: {
+      productAnalytics: preferences.productAnalytics,
+      crashReports: preferences.crashReports,
+    },
+  })
+}
+
+// stable per-machine anonymous telemetry id. every signed-out cli used to
+// report as the single literal distinct_id 'anonymous-cli', which merged all
+// first-run users into one posthog person and made "a new user's login hung"
+// impossible to see. created lazily on first use, persisted in config.json.
+export function readOrCreateAnonymousId(): string {
+  const existing = readSharedConfig().anonymousId
+  if (typeof existing === 'string' && existing.trim()) return existing
+  const created = `anon-cli-${randomUUID()}`
+  writeSharedConfig({ anonymousId: created })
+  return created
+}
+
+// --- background-upgrade notice --------------------------------------------
+//
+// the daemon auto-updates the engine runtime in the background (hourly), so
+// the only place its "updated to vX" line lands is the daemon's own stderr,
+// which nobody reads. it also drops a one-shot notice file here; the next
+// interactive CLI invocation prints it once and deletes it, so users learn
+// their engine moved without having to run `sootsim version`.
+
+export interface RuntimeUpgradeNotice {
+  from: string | null
+  to: string
+  at: number
+}
+
+export function runtimeUpgradeNoticePath(): string {
+  return path.join(sootsimHomeDir(), 'runtime-upgraded.json')
+}
+
+export function writeRuntimeUpgradeNotice(notice: RuntimeUpgradeNotice): void {
+  ensureSootsimHome()
+  const tmp = `${runtimeUpgradeNoticePath()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(notice)}\n`, 'utf8')
+  fs.renameSync(tmp, runtimeUpgradeNoticePath())
+}
+
+/** read + delete the pending upgrade notice, or null when none is pending.
+ *  deleting first-read keeps the banner one-shot even across racing CLIs. */
+export function consumeRuntimeUpgradeNotice(): RuntimeUpgradeNotice | null {
+  try {
+    const raw = fs.readFileSync(runtimeUpgradeNoticePath(), 'utf8')
+    fs.unlinkSync(runtimeUpgradeNoticePath())
+    const parsed = JSON.parse(raw) as Partial<RuntimeUpgradeNotice>
+    if (typeof parsed?.to !== 'string' || !parsed.to) return null
+    return {
+      from: typeof parsed.from === 'string' ? parsed.from : null,
+      to: parsed.to,
+      at: typeof parsed.at === 'number' ? parsed.at : 0,
+    }
+  } catch {
+    return null
+  }
+}
+
+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')
+}
+
+// listInstalledRuntimes + compareSemver live in @contrast/runtime-delivery:
+// they are delivery machinery (sorting the hosted catalog, deciding whether
+// channel latest is newer than active), shared with contrast, and this module
+// stays free of that dependency so every published `sootsim/*` export that
+// resolves through it keeps working with no bundling requirement.
+
+/** 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
+  /** repo-selected runtime versions currently served to connected sims. */
+  servedRuntimes?: string[]
+  /** 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
+}
+
+export interface DevBridgeLockfile {
+  schema: 1
+  pid: number
+  platform: NodeJS.Platform
+  bridgePort: number
+  runtimePort: number
+  /** http port of the vite shell dev server that owns this bridge (e.g. 5173).
+   *  optional: lockfiles written before this field existed still parse, and
+   *  readers fall back to the default shell URL. this is what lets the CLI
+   *  resolve the shell base URL and the bridge port from the SAME world
+   *  instead of mixing dev bridge + daemon runtime (the split-brain bug). */
+  shellPort?: number
+  cwd: string
+  startedAt: number
+  heartbeatAt: number
+  source: 'vite-dev'
+  /** repo-selected runtime versions currently served to connected sims. */
+  servedRuntimes?: string[]
+}
+
+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' &&
+        (parsed.servedRuntimes === undefined ||
+          (Array.isArray(parsed.servedRuntimes) &&
+            parsed.servedRuntimes.every((version) => typeof version === 'string')))
+      ) {
+        return parsed as DaemonLockfile
+      }
+      return null
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch {
+    return null
+  }
+}
+
+export function readDevBridgeLockfile(): DevBridgeLockfile | null {
+  try {
+    const fd = fs.openSync(devBridgeLockfilePath(), '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<DevBridgeLockfile>
+      if (
+        parsed &&
+        parsed.schema === 1 &&
+        parsed.source === 'vite-dev' &&
+        typeof parsed.pid === 'number' &&
+        typeof parsed.bridgePort === 'number' &&
+        typeof parsed.runtimePort === 'number' &&
+        typeof parsed.cwd === 'string' &&
+        typeof parsed.startedAt === 'number' &&
+        typeof parsed.heartbeatAt === 'number' &&
+        (parsed.shellPort === undefined || typeof parsed.shellPort === 'number') &&
+        (parsed.servedRuntimes === undefined ||
+          (Array.isArray(parsed.servedRuntimes) &&
+            parsed.servedRuntimes.every((version) => typeof version === 'string')))
+      ) {
+        return parsed as DevBridgeLockfile
+      }
+      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 isDevBridgeLockfileFresh(
+  lock: DevBridgeLockfile | null,
+  now = Date.now(),
+): lock is DevBridgeLockfile {
+  if (!lock) return false
+  if (now - lock.heartbeatAt > DAEMON_HEARTBEAT_STALE_MS) return false
+  try {
+    process.kill(lock.pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function readLiveRuntimeVersions(): string[] {
+  const versions = new Set<string>()
+  const daemon = readDaemonLockfile()
+  if (isDaemonLockfileFresh(daemon)) {
+    if (daemon.activeRuntime) versions.add(daemon.activeRuntime)
+    for (const version of daemon.servedRuntimes ?? []) versions.add(version)
+  }
+  const devBridge = readDevBridgeLockfile()
+  if (isDevBridgeLockfileFresh(devBridge)) {
+    for (const version of devBridge.servedRuntimes ?? []) versions.add(version)
+  }
+  return [...versions].sort()
+}
+
+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())
+}
+
+export function writeDevBridgeLockfile(data: DevBridgeLockfile): void {
+  ensureSootsimHome()
+  const tmp = `${devBridgeLockfilePath()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+  fs.renameSync(tmp, devBridgeLockfilePath())
+}
+
+/** 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 {}
+}
+
+export function removeDevBridgeLockfile(): void {
+  try {
+    fs.unlinkSync(devBridgeLockfilePath())
+  } catch {}
+}