rnxsim 0.0.0 → 0.1.313

package/src/poll-until.ts

@@ -0,0 +1,92 @@
+export interface PollUntilOptions {
+  timeoutMs: number
+  intervalMs?: number
+  label: string
+  signal?: AbortSignal
+}
+
+type PollReadOutcome<T> = { kind: 'value'; value: T } | { kind: 'error'; error: unknown }
+
+export async function pollUntil<T>(
+  read: () => Promise<T>,
+  ready: (value: T) => boolean,
+  options: PollUntilOptions,
+): Promise<T> {
+  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+    throw new Error('poll timeout must be a positive finite number')
+  }
+  const intervalMs = options.intervalMs ?? 100
+  if (!Number.isFinite(intervalMs) || intervalMs < 0) {
+    throw new Error('poll interval must be a non-negative finite number')
+  }
+
+  const deadline = Date.now() + options.timeoutMs
+  let lastError: unknown
+  const timeoutError = () =>
+    new Error(`${options.label} timed out after ${options.timeoutMs}ms`, {
+      cause: lastError,
+    })
+
+  options.signal?.throwIfAborted()
+  let rejectBoundary: (reason: unknown) => void = () => {}
+  const boundary = new Promise<never>((_, reject) => {
+    rejectBoundary = reject
+  })
+  const onAbort = () =>
+    rejectBoundary(
+      options.signal?.reason ??
+        new DOMException('The operation was aborted', 'AbortError'),
+    )
+  options.signal?.addEventListener('abort', onAbort, { once: true })
+  const deadlineTimer = setTimeout(
+    () => rejectBoundary(timeoutError()),
+    options.timeoutMs,
+  )
+
+  try {
+    while (true) {
+      if (Date.now() >= deadline) throw timeoutError()
+
+      const outcome = await Promise.race([
+        Promise.resolve()
+          .then(read)
+          .then(
+            (value): PollReadOutcome<T> => ({ kind: 'value', value }),
+            (error: unknown): PollReadOutcome<T> => ({ kind: 'error', error }),
+          ),
+        boundary,
+      ])
+
+      options.signal?.throwIfAborted()
+      if (outcome.kind === 'error') {
+        lastError = outcome.error
+      } else {
+        if (Date.now() >= deadline) throw timeoutError()
+        try {
+          if (ready(outcome.value)) return outcome.value
+        } catch (error) {
+          lastError = error
+        }
+      }
+
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) throw timeoutError()
+      if (intervalMs > 0) {
+        let intervalTimer: ReturnType<typeof setTimeout> | undefined
+        try {
+          await Promise.race([
+            new Promise<void>((resolve) => {
+              intervalTimer = setTimeout(resolve, Math.min(intervalMs, remaining))
+            }),
+            boundary,
+          ])
+        } finally {
+          clearTimeout(intervalTimer)
+        }
+      }
+    }
+  } finally {
+    clearTimeout(deadlineTimer)
+    options.signal?.removeEventListener('abort', onAbort)
+  }
+}

package/src/profiles.ts

@@ -0,0 +1,179 @@
+import fs from 'fs'
+import path from 'path'
+import { electronUserDataDir, ensureSootsimHome, profilesDir } from './home-paths'
+
+export const DEFAULT_PROFILE_ID = 'default'
+const PROFILE_INDEX_FILE = 'profiles.json'
+const PROFILE_INDEX_VERSION = 1 as const
+
+export interface StorageProfile {
+  id: string
+  createdAt: string
+  updatedAt: string
+}
+
+interface ProfileIndex {
+  version: 1
+  profiles: StorageProfile[]
+}
+
+export function normalizeProfileId(input: string): string {
+  const id = input.trim()
+  if (!id) throw new Error('profile id is required')
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+    throw new Error(
+      'profile ids must start with a letter or number and contain only letters, numbers, dot, dash, or underscore',
+    )
+  }
+  if (id === '.' || id === '..') throw new Error(`invalid profile id: ${id}`)
+  return id
+}
+
+export function profileIndexPath(): string {
+  return path.join(profilesDir(), PROFILE_INDEX_FILE)
+}
+
+export function electronProfilePartitionName(profileId: string): string {
+  return `sootsim-profile-${normalizeProfileId(profileId)}`
+}
+
+export function electronProfilePartition(profileId: string): string {
+  return `persist:${electronProfilePartitionName(profileId)}`
+}
+
+export function electronProfilePartitionDir(profileId: string): string {
+  return path.join(
+    electronUserDataDir(),
+    'Partitions',
+    electronProfilePartitionName(profileId),
+  )
+}
+
+export function playwrightProfileUserDataDir(profileId: string): string {
+  return path.join(profilesDir(), 'playwright', normalizeProfileId(profileId))
+}
+
+function readIndexRaw(): ProfileIndex {
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(profileIndexPath(), 'utf8'),
+    ) as Partial<ProfileIndex> | null
+    if (!parsed || parsed.version !== PROFILE_INDEX_VERSION) {
+      return { version: PROFILE_INDEX_VERSION, profiles: [] }
+    }
+    const profiles = Array.isArray(parsed.profiles)
+      ? parsed.profiles
+          .filter(
+            (profile): profile is StorageProfile =>
+              !!profile &&
+              typeof profile.id === 'string' &&
+              typeof profile.createdAt === 'string' &&
+              typeof profile.updatedAt === 'string',
+          )
+          .map((profile) => ({
+            id: normalizeProfileId(profile.id),
+            createdAt: profile.createdAt,
+            updatedAt: profile.updatedAt,
+          }))
+      : []
+    return { version: PROFILE_INDEX_VERSION, profiles }
+  } catch {
+    return { version: PROFILE_INDEX_VERSION, profiles: [] }
+  }
+}
+
+function sortProfiles(profiles: StorageProfile[]): StorageProfile[] {
+  return [...profiles].sort((a, b) => {
+    if (a.id === DEFAULT_PROFILE_ID) return -1
+    if (b.id === DEFAULT_PROFILE_ID) return 1
+    return a.id.localeCompare(b.id)
+  })
+}
+
+function withDefault(index: ProfileIndex): ProfileIndex {
+  if (index.profiles.some((profile) => profile.id === DEFAULT_PROFILE_ID)) {
+    return { ...index, profiles: sortProfiles(index.profiles) }
+  }
+  const now = new Date().toISOString()
+  return {
+    version: PROFILE_INDEX_VERSION,
+    profiles: sortProfiles([
+      { id: DEFAULT_PROFILE_ID, createdAt: now, updatedAt: now },
+      ...index.profiles,
+    ]),
+  }
+}
+
+function writeIndex(index: ProfileIndex): ProfileIndex {
+  ensureSootsimHome()
+  const next = withDefault(index)
+  const tmp = `${profileIndexPath()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+  fs.renameSync(tmp, profileIndexPath())
+  return next
+}
+
+export function listProfiles(): StorageProfile[] {
+  return writeIndex(readIndexRaw()).profiles
+}
+
+export function getProfile(id: string): StorageProfile | null {
+  const normalized = normalizeProfileId(id)
+  return listProfiles().find((profile) => profile.id === normalized) ?? null
+}
+
+export function ensureProfile(id = DEFAULT_PROFILE_ID): StorageProfile {
+  const normalized = normalizeProfileId(id)
+  const existing = getProfile(normalized)
+  if (existing) return existing
+  return createProfile(normalized)
+}
+
+export function createProfile(id: string): StorageProfile {
+  const normalized = normalizeProfileId(id)
+  const index = withDefault(readIndexRaw())
+  if (index.profiles.some((profile) => profile.id === normalized)) {
+    throw new Error(`profile already exists: ${normalized}`)
+  }
+  const now = new Date().toISOString()
+  const profile = { id: normalized, createdAt: now, updatedAt: now }
+  writeIndex({ version: PROFILE_INDEX_VERSION, profiles: [...index.profiles, profile] })
+  return profile
+}
+
+export function nextGeneratedProfileId(): string {
+  const existing = new Set(listProfiles().map((profile) => profile.id))
+  for (let i = 1; i < 10_000; i++) {
+    const id = `profile-${i}`
+    if (!existing.has(id)) return id
+  }
+  throw new Error('could not allocate a new profile id')
+}
+
+export function deleteProfile(id: string): StorageProfile {
+  const normalized = normalizeProfileId(id)
+  if (normalized === DEFAULT_PROFILE_ID) {
+    throw new Error('the default profile cannot be deleted; clear it instead')
+  }
+  const index = withDefault(readIndexRaw())
+  const profile = index.profiles.find((entry) => entry.id === normalized)
+  if (!profile) throw new Error(`profile not found: ${normalized}`)
+  writeIndex({
+    version: PROFILE_INDEX_VERSION,
+    profiles: index.profiles.filter((entry) => entry.id !== normalized),
+  })
+  clearProfileStorage(normalized)
+  return profile
+}
+
+export function clearProfileStorage(id: string): void {
+  const normalized = normalizeProfileId(id)
+  for (const dir of [
+    electronProfilePartitionDir(normalized),
+    playwrightProfileUserDataDir(normalized),
+  ]) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true })
+    } catch {}
+  }
+}

package/src/public-brand.ts

@@ -0,0 +1,9 @@
+const name = 'rnx'
+
+export const rnxPublicBrand = Object.freeze({
+  name,
+  packageName: 'rnxsim',
+  commandName: 'rnxsim',
+  domain: 'rnxsim.com',
+  origin: 'https://rnxsim.com',
+})

package/src/render-mode.ts

@@ -0,0 +1,27 @@
+export type RenderMode = 'worker'
+
+// worker rendering is now the only supported mode.
+export function getRenderMode(_searchParams: URLSearchParams): RenderMode {
+  return 'worker'
+}
+
+export function isRenderWorkerMode(_searchParams: URLSearchParams): boolean {
+  return true
+}
+
+export function isRenderMainMode(_searchParams: URLSearchParams): boolean {
+  return false
+}
+
+export function hasRenderWorkerBootstrap(
+  workerModuleBaseUrl: string | null | undefined,
+): boolean {
+  return typeof workerModuleBaseUrl === 'string' && workerModuleBaseUrl.length > 0
+}
+
+export function shouldEnableRenderWorker(
+  _searchParams: URLSearchParams,
+  workerModuleBaseUrl: string | null | undefined,
+): boolean {
+  return hasRenderWorkerBootstrap(workerModuleBaseUrl)
+}

package/src/runtime-assets.ts

@@ -0,0 +1,228 @@
+// helpers for serving the installed sootsim engine runtime from framework
+// dev servers. the runtime is managed by `sootsim runtime install` and lives
+// under ~/.sootsim/runtimes/<version>.
+
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { isValidRuntimeVersion } from '@contrast/runtime-delivery'
+import { readActiveRuntime, runtimeDir } from './home-paths.ts'
+
+export const SOOTSIM_RUNTIME_MISSING_MESSAGE =
+  '[rnx] no engine runtime installed — run `rnxsim setup`, or `rnxsim runtime install`'
+
+// --- dev-checkout mode boundary --------------------------------------------
+//
+// there is exactly one rule for which engine gets served: INSIDE the Contrast
+// monorepo dev checkout the fresh dev-stack build (public/sootsim, kept current
+// by `bun dev`'s watch:sootsim) IS the engine; OUTSIDE it (a published CLI in a
+// user's project, or an isolated home) the installed runtime IS. this is a mode
+// boundary, not a preference or a runtime fallback chain — the check is
+// structural (the monorepo layout is present next to this module) and
+// deterministic (the dev build's files exist). it exists because the daemon and
+// the /__soot plugin otherwise serve ~/.sootsim/runtimes/<active>, a PUBLISHED
+// runtime that `bun dev` never refreshes, so local engine edits are invisible
+// until a manual publish — the silent trap that cost a full night of
+// already-fixed bugs re-reproducing.
+//
+// the isolated CI headless path (scripts/local-publish-runtime.sh) sets
+// SOOTSIM_HOME to a dedicated dir precisely to validate the published-runtime
+// code path; keying off that EXISTING isolation env keeps it (and packaged
+// electron with a custom home) on the installed runtime.
+let _monorepoRootCache: string | null | undefined
+
+function findMonorepoRoot(): string | null {
+  if (_monorepoRootCache !== undefined) return _monorepoRootCache
+  let dir = path.dirname(fileURLToPath(import.meta.url))
+  // walk up until we find the Contrast monorepo: it has packages/sootsim-engine and
+  // a public/sootsim dev-build output slot. bounded by the filesystem root.
+  for (let i = 0; i < 12 && dir !== path.dirname(dir); i++) {
+    if (
+      fs.existsSync(path.join(dir, 'packages/sootsim-engine/package.json')) &&
+      fs.existsSync(path.join(dir, 'public/sootsim'))
+    ) {
+      _monorepoRootCache = dir
+      return dir
+    }
+    dir = path.dirname(dir)
+  }
+  _monorepoRootCache = null
+  return null
+}
+
+/** the fresh dev-stack engine build to serve when running inside the Contrast
+ *  monorepo dev checkout, or null when the installed runtime should serve
+ *  (published CLI, packaged electron, or an isolated SOOTSIM_HOME). */
+export function resolveDevCheckoutRuntimeRoot(): string | null {
+  // an explicit home that has a STAGED/active runtime is the isolation the
+  // CI/local-publish path sets up to validate the installed-runtime code path —
+  // honor that staged runtime. an explicit home with NO active runtime is just
+  // an isolated dev daemon (own lockfile, doesn't clobber ~/.sootsim), which
+  // still wants the dev build; and the default home (SOOTSIM_HOME unset) always
+  // does. keying on "explicit home + a runtime deliberately staged there" keeps
+  // it structural, not a bespoke toggle.
+  if (process.env.SOOTSIM_HOME && readActiveRuntime()) return null
+  const root = findMonorepoRoot()
+  if (!root) return null
+  const devBuild = path.join(root, 'public/sootsim')
+  // require the runtime shape the installed runtime also has, so serving it is
+  // a drop-in (index.html shell + engine/ + engine-tenant/worker.js tenant).
+  if (
+    fs.existsSync(path.join(devBuild, 'index.html')) &&
+    fs.existsSync(path.join(devBuild, 'engine/index.html')) &&
+    fs.existsSync(path.join(devBuild, 'engine-tenant/worker.js'))
+  ) {
+    return devBuild
+  }
+  return null
+}
+
+const MIME_TYPES: Record<string, string> = {
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.css': 'text/css',
+  '.html': 'text/html',
+  '.wasm': 'application/wasm',
+  '.json': 'application/json',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.glb': 'model/gltf-binary',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+}
+
+const ROOT_RUNTIME_PATHS = [
+  '/assets/',
+  '/engine/',
+  '/engine-tenant/',
+  '/photos/',
+  '/three-mode/',
+  '/fonts/',
+  '/icons/',
+  '/sounds/',
+  '/spike/',
+  '/test-wallpaper.jpg',
+  '/preview-sw.js',
+  '/sootsim.svg',
+]
+
+export function resolveActiveRuntimeRoot(): string | null {
+  // mode boundary: inside the dev checkout the dev-stack build is the engine.
+  const devRoot = resolveDevCheckoutRuntimeRoot()
+  if (devRoot) return devRoot
+  const active = readActiveRuntime()
+  if (!active) return null
+  const dir = runtimeDir(active)
+  if (!fs.existsSync(path.join(dir, 'index.html'))) return null
+  return dir
+}
+
+const RUNTIME_VERSION_HOSTNAME_SUFFIX = '.runtime.localhost'
+
+export function runtimeVersionHostname(version: string): string {
+  const trimmed = version.trim()
+  if (!isValidRuntimeVersion(trimmed)) {
+    throw new Error(`invalid rnx runtime version: ${version}`)
+  }
+  const encoded = Buffer.from(trimmed, 'utf8').toString('hex')
+  const labels = encoded.match(/.{1,60}/g)
+  if (!labels) throw new Error(`invalid rnx runtime version: ${version}`)
+  return `${labels.join('.')}${RUNTIME_VERSION_HOSTNAME_SUFFIX}`
+}
+
+export function isRuntimeVersionHostname(hostname: string): boolean {
+  return hostname.toLowerCase().endsWith(RUNTIME_VERSION_HOSTNAME_SUFFIX)
+}
+
+export function runtimeVersionFromHostname(hostname: string): string | null {
+  if (!isRuntimeVersionHostname(hostname)) return null
+  const labels = hostname.slice(0, -RUNTIME_VERSION_HOSTNAME_SUFFIX.length).split('.')
+  if (labels.length === 0 || labels.some((label) => !/^[0-9a-f]{1,60}$/i.test(label))) {
+    return null
+  }
+  const encoded = labels.join('')
+  if (encoded.length % 2 !== 0) return null
+  try {
+    const version = Buffer.from(encoded, 'hex').toString('utf8')
+    return isValidRuntimeVersion(version) ? version : null
+  } catch {
+    return null
+  }
+}
+
+export function resolveInstalledRuntimeRoot(version: string): string | null {
+  const dir = runtimeDir(version)
+  if (!fs.existsSync(path.join(dir, 'index.html'))) return null
+  return dir
+}
+
+/** select one immutable installed runtime for a version-owned origin. ordinary
+ *  localhost requests follow the active runtime; a malformed or unavailable
+ *  version origin fails closed instead of borrowing active assets. */
+export function resolveRuntimeRootForHostname(hostname: string): string | null {
+  if (!isRuntimeVersionHostname(hostname)) return resolveActiveRuntimeRoot()
+  const version = runtimeVersionFromHostname(hostname)
+  return version ? resolveInstalledRuntimeRoot(version) : null
+}
+
+export function resolveRuntimeRootForRequestHost(
+  host: string | undefined,
+): string | null {
+  if (!host) return resolveActiveRuntimeRoot()
+  try {
+    return resolveRuntimeRootForHostname(new URL(`http://${host}`).hostname)
+  } catch {
+    return null
+  }
+}
+
+export function isRootRuntimeAssetPath(pathname: string): boolean {
+  return ROOT_RUNTIME_PATHS.some((p) => pathname === p || pathname.startsWith(p))
+}
+
+export function resolveRuntimeFilePath(
+  runtimeRoot: string,
+  pathname: string,
+): string | null {
+  if (!pathname.startsWith('/')) return null
+  if (pathname.includes('\0') || pathname.includes('\\')) return null
+  for (const segment of pathname.split('/')) {
+    if (segment === '..') return null
+  }
+
+  const fullPath = path.resolve(runtimeRoot, pathname.replace(/^\/+/, ''))
+  const rootWithSep = runtimeRoot.endsWith(path.sep)
+    ? runtimeRoot
+    : runtimeRoot + path.sep
+  if (!fullPath.startsWith(rootWithSep) && fullPath !== runtimeRoot) return null
+  if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) return null
+  return fullPath
+}
+
+export function serveRuntimeFile(req: any, res: any, fullPath: string) {
+  const ext = path.extname(fullPath)
+  const stat = fs.statSync(fullPath)
+  const lastModified = stat.mtime.toUTCString()
+  res.setHeader('content-type', MIME_TYPES[ext] || 'application/octet-stream')
+  // these urls are STABLE across dev rebuilds and runtime version switches
+  // (worker.js, canvaskit-graphite.wasm, the html shells are unhashed), so the
+  // browser must revalidate every load — the old year-long immutable here made every
+  // new tab run a stale cached engine-tenant worker.js against a fresh engine,
+  // which also broke `do reload` ("bridge never reconnected"). no-cache +
+  // last-modified keeps repeat loads cheap 304s on localhost.
+  res.setHeader('cache-control', 'no-cache')
+  res.setHeader('last-modified', lastModified)
+  if (req?.headers?.['if-modified-since'] === lastModified) {
+    res.statusCode = 304
+    res.end()
+    return
+  }
+  fs.createReadStream(fullPath).pipe(res)
+}

package/src/runtime-delivery.ts

@@ -0,0 +1,54 @@
+// sootsim's binding of the shared runtime-delivery machinery.
+//
+// the machinery itself (hosted manifest, sha256-verified tarballs, channels,
+// channel resolution, and auto-update) lives in @contrast/runtime-delivery and
+// knows nothing about sootsim. this file supplies sootsim's identity: ~/.sootsim, the
+// SOOTSIM_* env overrides, and the contrast.dev/runtimes hosting layout.
+//
+// @contrast/runtime-delivery is an internal workspace package that is never
+// published, so both the CLI bundle and dist-lib inline it (see the `alias`
+// entry in scripts/build-cli.ts). pack-smoke fails the build if it ever leaks
+// out as a bare require.
+
+import { createRuntimeDelivery, type RuntimeProduct } from '@contrast/runtime-delivery'
+import {
+  cacheDir,
+  configFilePath,
+  ensureSootsimHome,
+  readActiveRuntime,
+  runtimeDir,
+  runtimesDir,
+  writeActiveRuntime,
+} from './home-paths.ts'
+import { rnxPublicBrand } from './public-brand.ts'
+
+export const DEFAULT_RUNTIME_CDN_ORIGIN = 'https://contrast.dev'
+
+/** the official curated changelog and the machine-readable release feed. the
+ *  SootSim site is static, so its /api traffic is owned by contrast.dev. */
+export const SOOTSIM_CHANGELOG_URL = `${rnxPublicBrand.origin}/changelog`
+export const SOOTSIM_CHANGELOG_API_URL = 'https://contrast.dev/api/changelog/sootsim'
+
+export const SOOTSIM_RUNTIME_PRODUCT: RuntimeProduct = {
+  id: 'sootsim',
+  defaultCdnOrigin: DEFAULT_RUNTIME_CDN_ORIGIN,
+  manifestPath: '/runtimes/manifest.json',
+  tarballPath: (version) => `/runtimes/sootsim-runtime-${version}.tar.gz`,
+  // the engine runtime is a static SPA: shell at the root, engine/ and
+  // engine-tenant/ beneath it. index.html is what the daemon and the
+  // vite/metro plugins serve, so its absence means the tarball is not one.
+  installedMarker: 'index.html',
+  env: {
+    cdnOrigin: 'SOOTSIM_CDN_ORIGIN',
+    channel: 'SOOTSIM_RUNTIME_CHANNEL',
+  },
+  ensureHome: ensureSootsimHome,
+  configFile: configFilePath,
+  runtimesDir,
+  runtimeDir,
+  cacheDir,
+  readActiveRuntime,
+  writeActiveRuntime,
+}
+
+export const sootsimRuntime = createRuntimeDelivery(SOOTSIM_RUNTIME_PRODUCT)