sootsim 0.1.82 → 0.1.84

package/scripts/demo-app-registry.ts

@@ -0,0 +1,989 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import type { SootSimConfig } from '../src/config.ts'
+
+export interface DemoApp {
+  name: string
+  label: string
+  dir: string
+  preferredPort: number
+  framework: 'expo' | 'one' | 'rock'
+  runtimeConfig?: SootSimConfig
+  sidecars?: DemoSidecar[]
+  prepare?: () => void | Promise<void>
+  command: (port: number) => { cmd: string; env?: Record<string, string> }
+  disabled?: boolean
+  note?: string
+  // override the dev-server readiness timeout (default 90s). use for stacks
+  // like takeout's `bun lite` that bring up postgres + zero + minio + One
+  // and need longer to settle on a cold start.
+  readyTimeoutMs?: number
+  // env vars this demo can consume for credentials/sign-in. the demo launcher
+  // prints their presence/absence in its summary so you know whether an
+  // app can auto-login. format: { HANDLE: 'natew.bsky.social' } to show a
+  // known handle even when stored elsewhere.
+  credentials?: {
+    envVars?: string[]
+    known?: Record<string, string>
+    note?: string
+  }
+}
+
+export interface DemoSidecar {
+  name: string
+  port: number
+  readyPath?: string
+  command: () => { cmd: string; env?: Record<string, string> }
+}
+
+const HOME = homedir()
+
+function findWorkspaceRoot(startDir: string): string | null {
+  let dir = startDir
+  while (true) {
+    if (
+      existsSync(join(dir, 'pnpm-workspace.yaml')) ||
+      existsSync(join(dir, 'turbo.json')) ||
+      existsSync(join(dir, 'nx.json')) ||
+      existsSync(join(dir, 'lerna.json'))
+    ) {
+      return dir
+    }
+
+    const packageJsonPath = join(dir, 'package.json')
+    if (existsSync(packageJsonPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+          workspaces?: unknown
+        }
+        if (pkg.workspaces) return dir
+      } catch {}
+    }
+
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function resolveWorkspaceScriptPath(
+  workspaceRelativePath: string,
+  packageRelativePath: string,
+): string {
+  const workspaceRoot = findWorkspaceRoot(process.cwd())
+  const candidates = [
+    workspaceRoot ? resolve(workspaceRoot, workspaceRelativePath) : null,
+    resolve(process.cwd(), workspaceRelativePath),
+    resolve(process.cwd(), packageRelativePath),
+  ].filter((candidate): candidate is string => Boolean(candidate))
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+
+  return candidates[0] ?? resolve(process.cwd(), workspaceRelativePath)
+}
+
+const getExpensifyProxyScript = () =>
+  resolveWorkspaceScriptPath(
+    'packages/sootsim-engine/scripts/expensify-web-proxy.ts',
+    'scripts/expensify-web-proxy.ts',
+  )
+const getRainbowMetadataProxyScript = () =>
+  resolveWorkspaceScriptPath(
+    'packages/sootsim-engine/scripts/rainbow-metadata-proxy.ts',
+    'scripts/rainbow-metadata-proxy.ts',
+  )
+const getMattermostRNUtilsNativeModule = () =>
+  resolveWorkspaceScriptPath(
+    'packages/compat/src/stubs/mattermost-rnutils-native.ts',
+    '../compat/src/stubs/mattermost-rnutils-native.ts',
+  )
+const getMattermostKeychainNativeModule = () =>
+  resolveWorkspaceScriptPath(
+    'packages/compat/src/stubs/native-seams/react-native-keychain-manager.ts',
+    '../compat/src/stubs/native-seams/react-native-keychain-manager.ts',
+  )
+const getMattermostNetworkClientNativeModule = () =>
+  resolveWorkspaceScriptPath(
+    'packages/compat/src/stubs/mattermost-network-client-native.ts',
+    '../compat/src/stubs/mattermost-network-client-native.ts',
+  )
+const getMattermostPreviewServerScript = () =>
+  resolveWorkspaceScriptPath(
+    'packages/sootsim-engine/scripts/mattermost-preview-server.ts',
+    'scripts/mattermost-preview-server.ts',
+  )
+const EXPENSIFY_NATIVE_PROXY_ENV = {
+  USE_NGROK: 'true',
+  NGROK_URL: 'http://localhost:9000/',
+  SECURE_NGROK_URL: 'http://localhost:9000/',
+}
+const MATTERMOST_DIR = join(HOME, 'github/mattermost-mobile')
+const UNISWAP_REPO_DIR = join(HOME, 'github/uniswap-interface')
+const UNISWAP_APP_DIR = join(UNISWAP_REPO_DIR, 'apps/mobile')
+const UNISWAP_ENV_LOCAL_FILE = join(UNISWAP_REPO_DIR, '.env.defaults.local')
+const UNISWAP_PLACEHOLDER = 'stored-in-.env.local'
+const UNISWAP_DEMO_ENV_MARKER = '# sootsim demo env overrides'
+const UNISWAP_FORCE_UPGRADE_HOOK_FILE = join(
+  UNISWAP_REPO_DIR,
+  'packages/uniswap/src/features/forceUpgrade/hooks/useForceUpgradeStatus.ts',
+)
+const UNISWAP_FORCE_UPGRADE_NOTIFICATION_FILE = join(
+  UNISWAP_REPO_DIR,
+  'apps/mobile/src/notification-service/data-sources/createForceUpgradeNotificationDataSource.ts',
+)
+const UNISWAP_FORCE_UPGRADE_PATCH_MARKER = 'SOOTSIM_DEMO_DISABLE_FORCE_UPGRADE'
+
+function parseEnvFile(filePath: string): Record<string, string> {
+  if (!existsSync(filePath)) return {}
+
+  const env: Record<string, string> = {}
+  const source = readFileSync(filePath, 'utf8')
+  for (const rawLine of source.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/)
+    if (!match) continue
+
+    let value = match[2].trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+
+    env[match[1]] = value
+  }
+
+  return env
+}
+
+function isUsableUniswapEnvValue(value: string | undefined): value is string {
+  if (!value) return false
+  const trimmed = value.trim()
+  if (!trimmed) return false
+  if (trimmed.includes(UNISWAP_PLACEHOLDER)) return false
+  if (trimmed === 'TRADING_API_KEY' || trimmed === 'UNISWAP_API_KEY') return false
+  return true
+}
+
+function pickEnvValue(
+  sources: Array<Record<string, string | undefined>>,
+  keys: string[],
+): string | undefined {
+  for (const source of sources) {
+    for (const key of keys) {
+      const value = source[key]
+      if (isUsableUniswapEnvValue(value)) return value.trim()
+    }
+  }
+  return undefined
+}
+
+function resolveUniswapDemoEnv(): Record<string, string> {
+  const localEnv = parseEnvFile(UNISWAP_ENV_LOCAL_FILE)
+  const webEnv = parseEnvFile(join(UNISWAP_REPO_DIR, 'apps/web/.env'))
+  const sources: Array<Record<string, string | undefined>> = [
+    process.env as Record<string, string | undefined>,
+    localEnv,
+    webEnv,
+  ]
+
+  const env: Record<string, string> = {}
+  const bindings: Array<[target: string, aliases: string[]]> = [
+    ['AMPLITUDE_PROXY_URL_OVERRIDE', ['REACT_APP_AMPLITUDE_PROXY_URL']],
+    ['QUICKNODE_ENDPOINT_NAME', ['REACT_APP_QUICKNODE_ENDPOINT_NAME']],
+    ['QUICKNODE_ENDPOINT_TOKEN', ['REACT_APP_QUICKNODE_ENDPOINT_TOKEN']],
+    ['INFURA_KEY', ['REACT_APP_INFURA_KEY']],
+    ['STATSIG_API_KEY', ['REACT_APP_STATSIG_API_KEY']],
+    ['STATSIG_PROXY_URL_OVERRIDE', ['REACT_APP_STATSIG_PROXY_URL']],
+    ['WALLETCONNECT_PROJECT_ID', ['REACT_APP_WALLET_CONNECT_PROJECT_ID']],
+    ['WALLETCONNECT_PROJECT_ID_BETA', ['REACT_APP_WALLET_CONNECT_PROJECT_ID']],
+    ['WALLETCONNECT_PROJECT_ID_DEV', ['REACT_APP_WALLET_CONNECT_PROJECT_ID']],
+    ['TRADING_API_KEY', ['REACT_APP_TRADING_API_KEY']],
+    ['UNISWAP_API_KEY', []],
+  ]
+
+  for (const [target, aliases] of bindings) {
+    const value = pickEnvValue(sources, [target, ...aliases])
+    if (!value) continue
+    env[target] = value
+    for (const alias of aliases) {
+      env[alias] = value
+    }
+  }
+
+  const hasPrivateGatewayKeys =
+    isUsableUniswapEnvValue(env.TRADING_API_KEY) &&
+    isUsableUniswapEnvValue(env.UNISWAP_API_KEY)
+
+  if (!hasPrivateGatewayKeys) {
+    // fall back to the public web gateway family when private mobile gateway
+    // keys are unavailable. this won't unlock every endpoint, but it avoids
+    // the worst ios.wallet-specific failures in local sootsim demos.
+    const publicGraphqlUrl =
+      pickEnvValue(sources, ['GRAPHQL_URL_OVERRIDE', 'REACT_APP_AWS_API_ENDPOINT']) ||
+      'https://interface.gateway.uniswap.org/v1/graphql'
+
+    env.API_BASE_URL_OVERRIDE = 'https://interface.gateway.uniswap.org'
+    env.API_BASE_URL_V2_OVERRIDE = 'https://interface.gateway.uniswap.org/v2'
+    env.GRAPHQL_URL_OVERRIDE = publicGraphqlUrl
+    env.TRADING_API_URL_OVERRIDE =
+      'https://trading-api-labs.interface.gateway.uniswap.org'
+    env.FOR_API_URL_OVERRIDE =
+      'https://for.interface.gateway.uniswap.org/v2/FOR.v1.FORService'
+  }
+
+  return env
+}
+
+function ensureUniswapDemoEnvLocal(): void {
+  const existingSource = existsSync(UNISWAP_ENV_LOCAL_FILE)
+    ? readFileSync(UNISWAP_ENV_LOCAL_FILE, 'utf8')
+    : ''
+
+  if (existingSource && !existingSource.includes(UNISWAP_DEMO_ENV_MARKER)) {
+    return
+  }
+
+  const env = resolveUniswapDemoEnv()
+  const lines = [UNISWAP_DEMO_ENV_MARKER]
+  for (const [key, value] of Object.entries(env).sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`${key}=${JSON.stringify(value)}`)
+  }
+  lines.push('')
+  writeFileSync(UNISWAP_ENV_LOCAL_FILE, `${lines.join('\n')}\n`)
+}
+
+function ensureUniswapForceUpgradePatched(): void {
+  const hookNeedle = `export function useForceUpgradeStatus(): ForceUpgradeStatus {\n`
+  const hookPatch =
+    `  // sootsim demo: bypass the force-upgrade gate during local engine demos.\n` +
+    `  return 'not-required'\n\n`
+  const hookLegacyPatch =
+    `  // sootsim demo: bypass the force-upgrade gate during local engine demos.\n` +
+    `  if (process.env.${UNISWAP_FORCE_UPGRADE_PATCH_MARKER} === 'true') {\n` +
+    `    return 'not-required'\n` +
+    `  }\n\n`
+
+  const notificationNeedle = `  const getForceUpgradeStatus = (): ForceUpgradeStatus => {\n`
+  const notificationPatch =
+    `    // sootsim demo: bypass the force-upgrade gate during local engine demos.\n` +
+    `    return 'not-required'\n\n`
+  const notificationLegacyPatch =
+    `    // sootsim demo: bypass the force-upgrade gate during local engine demos.\n` +
+    `    if (process.env.${UNISWAP_FORCE_UPGRADE_PATCH_MARKER} === 'true') {\n` +
+    `      return 'not-required'\n` +
+    `    }\n\n`
+
+  const patchWithMigration = (
+    filePath: string,
+    needle: string,
+    patch: string,
+    legacyPatch: string,
+  ) => {
+    const source = readFileSync(filePath, 'utf8')
+    if (source.includes(patch)) return
+    if (source.includes(legacyPatch)) {
+      writeFileSync(filePath, source.replace(legacyPatch, patch))
+      return
+    }
+    if (!source.includes(needle)) {
+      throw new Error(
+        `uniswap demo patch failed: expected snippet not found in ${filePath}`,
+      )
+    }
+    writeFileSync(filePath, source.replace(needle, `${needle}${patch}`))
+  }
+
+  patchWithMigration(
+    UNISWAP_FORCE_UPGRADE_HOOK_FILE,
+    hookNeedle,
+    hookPatch,
+    hookLegacyPatch,
+  )
+  patchWithMigration(
+    UNISWAP_FORCE_UPGRADE_NOTIFICATION_FILE,
+    notificationNeedle,
+    notificationPatch,
+    notificationLegacyPatch,
+  )
+}
+
+const JOPLIN_DIR = join(HOME, 'github/joplin')
+const JOPLIN_APP_DIR = join(JOPLIN_DIR, 'packages/app-mobile')
+// joplin's metro.config.js adds every @joplin/* source dir as a metro
+// `watchFolders` entry. on machines where watchman has
+// `enforce_root_files: true` set globally (soot's setup), each watched
+// root must contain a `.watchmanconfig` or metro crash-exits before
+// serving its first bundle. upstream joplin only ships the file in
+// `app-mobile` and `whisper-voice-typing`; the other watched packages
+// don't have one, so we touch them ourselves. idempotent.
+const JOPLIN_WATCH_ROOTS = [
+  'packages/lib',
+  'packages/renderer',
+  'packages/turndown',
+  'packages/turndown-plugin-gfm',
+  'packages/editor',
+  'packages/tools',
+  'packages/utils',
+  'packages/fork-htmlparser2',
+  'packages/fork-uslug',
+  'packages/fork-sax',
+  'packages/htmlpack',
+  'packages/react-native-saf-x',
+  'packages/react-native-alarm-notification',
+]
+
+function ensureJoplinWatchmanConfigs(): void {
+  if (!existsSync(JOPLIN_DIR)) return
+  for (const rel of JOPLIN_WATCH_ROOTS) {
+    const dir = join(JOPLIN_DIR, rel)
+    if (!existsSync(dir)) continue
+    const cfg = join(dir, '.watchmanconfig')
+    if (!existsSync(cfg)) writeFileSync(cfg, '{}\n')
+  }
+}
+
+// joplin's metro consumes per-package tsc emit (.js next to .ts), rollup
+// output for `@joplin/turndown(-plugin-gfm)`, and gulp-generated
+// `pluginAssets/index.js` for KaTeX/Mermaid bundles. yarn's root postinstall
+// runs `gulp build` which is supposed to produce all of these, but it fails
+// silently when run on a fresh clone before workspace builds have completed
+// (turndown's `prepare` script doesn't fire in foreach mode). detect the
+// three sentinels and run `yarn buildParallel` if any are missing. one-time
+// cost (~2 minutes), idempotent thereafter.
+const JOPLIN_BUILD_SENTINELS = [
+  'packages/lib/models/Setting.js',
+  'packages/turndown/lib/turndown.cjs.js',
+  'packages/app-mobile/pluginAssets/index.js',
+]
+
+function ensureJoplinBuilt(): void {
+  if (!existsSync(JOPLIN_DIR)) return
+  const missing = JOPLIN_BUILD_SENTINELS.filter(
+    (rel) => !existsSync(join(JOPLIN_DIR, rel)),
+  )
+  if (missing.length === 0) return
+
+  const { execSync } =
+    require('node:child_process') as typeof import('node:child_process')
+  // buildParallel walks the workspace topologically and runs `build` in each
+  // package, then `yarn tsc`. NO_FLIPPER=1 matches joplin's documented
+  // mobile build flag. unset CI so yarn workspaces foreach doesn't reduce
+  // parallelism to 1.
+  execSync('yarn buildParallel', {
+    cwd: JOPLIN_DIR,
+    stdio: 'inherit',
+    env: { ...process.env, NO_FLIPPER: '1', CI: '' },
+  })
+
+  const stillMissing = JOPLIN_BUILD_SENTINELS.filter(
+    (rel) => !existsSync(join(JOPLIN_DIR, rel)),
+  )
+  if (stillMissing.length > 0) {
+    throw new Error(
+      `joplin demo: yarn buildParallel did not produce: ${stillMissing.join(', ')}`,
+    )
+  }
+}
+
+const RAINBOW_DIR = join(HOME, 'github/rainbow')
+const RAINBOW_GRAPHQL_DIR = join(RAINBOW_DIR, 'src/graphql')
+const RAINBOW_GRAPHQL_CONFIG_FILE = join(RAINBOW_GRAPHQL_DIR, 'config.js')
+const RAINBOW_NETWORKS_FILE = join(RAINBOW_DIR, 'src/references/networks.json')
+const RAINBOW_METADATA_BASE_URL = 'https://metadata.p.rainbow.me'
+const RAINBOW_METADATA_PROXY_PORT = 9011
+const RAINBOW_DEMO_METADATA_BASE_URL = `http://127.0.0.1:${RAINBOW_METADATA_PROXY_PORT}`
+const RAINBOW_PUBLIC_ENS_GRAPHQL_URL =
+  'https://api.thegraph.com/subgraphs/name/ensdomains/ens'
+const RAINBOW_DEMO_QUOTE_SIGNER = '0x0000000000000000000000000000000000000000'
+const RAINBOW_DEMO_RELAY_URL = 'https://relay.rainbow.me'
+const RAINBOW_DEMO_MASTER_KEY =
+  'sootsim-rainbow-demo-master-key-do-not-use-for-real-wallets'
+const RAINBOW_DEMO_RPC_PROXY_BASE_URL = 'https://rpc.rainbow.me/v1'
+const RAINBOW_DEMO_RPC_API_KEY = ''
+const RAINBOW_DEMO_PUBLIC_RPC_URLS: Record<string, string> = {
+  '1': 'https://ethereum-rpc.publicnode.com',
+}
+const RAINBOW_DEMO_SERVICE_API_KEY = 'sootsim-rainbow-demo-api-key'
+const RAINBOW_DEMO_SECURE_WALLET_HASH_KEY =
+  '0x736f6f7473696d2d7261696e626f772d64656d6f2d686173682d6b6579000000'
+const RAINBOW_GRAPHQL_SENTINELS = [
+  'src/graphql/__generated__/ens.ts',
+  'src/graphql/__generated__/metadata.ts',
+  'src/graphql/__generated__/metadataPOST.ts',
+]
+
+function runRainbowSetupCommand(command: string, cwd: string): void {
+  const { execSync } =
+    require('node:child_process') as typeof import('node:child_process')
+  execSync(command, {
+    cwd,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      METADATA_BASE_URL: RAINBOW_METADATA_BASE_URL,
+      RAINBOW_RELAY_QUOTE_SIGNER:
+        process.env.RAINBOW_RELAY_QUOTE_SIGNER ?? RAINBOW_DEMO_QUOTE_SIGNER,
+    },
+  })
+}
+
+function ensureRainbowGraphqlConfig(): void {
+  if (!existsSync(RAINBOW_GRAPHQL_DIR)) return
+
+  const source = existsSync(RAINBOW_GRAPHQL_CONFIG_FILE)
+    ? readFileSync(RAINBOW_GRAPHQL_CONFIG_FILE, 'utf8')
+    : ''
+  if (
+    source.includes(RAINBOW_PUBLIC_ENS_GRAPHQL_URL) &&
+    source.includes(RAINBOW_METADATA_BASE_URL)
+  ) {
+    return
+  }
+
+  writeFileSync(
+    RAINBOW_GRAPHQL_CONFIG_FILE,
+    `exports.config = {
+  ens: {
+    __name: 'ens',
+    document: './queries/ens.graphql',
+    schema: {
+      method: 'POST',
+      url: '${RAINBOW_PUBLIC_ENS_GRAPHQL_URL}',
+    },
+  },
+  metadata: {
+    __name: 'metadata',
+    document: './queries/metadata.graphql',
+    schema: { method: 'GET', url: '${RAINBOW_METADATA_BASE_URL}/v1/graph' },
+  },
+  metadataPOST: {
+    __name: 'metadataPOST',
+    document: './queries/metadata.graphql',
+    schema: { method: 'POST', url: '${RAINBOW_METADATA_BASE_URL}/v1/graph' },
+  },
+  arc: {
+    __name: 'arc',
+    document: './queries/arc.graphql',
+    schema: {
+      method: 'GET',
+      url: 'https://arc-graphql.rainbow.me/graphql',
+      headers: {
+        'x-api-key': 'ARC_GRAPHQL_API_KEY',
+      },
+    },
+  },
+  arcDev: {
+    __name: 'arcDev',
+    document: './queries/arc.graphql',
+    schema: {
+      method: 'GET',
+      url: 'https://arc-graphql.rainbowdotme.workers.dev/graphql',
+      headers: {},
+    },
+  },
+};
+`,
+  )
+}
+
+function resolveRainbowDemoEnv(): Record<string, string> {
+  const env: Record<string, string> = {
+    ENABLE_DEV_MODE: '1',
+    IS_TESTING: 'false',
+    METADATA_BASE_URL:
+      process.env.RAINBOW_METADATA_BASE_URL ?? RAINBOW_DEMO_METADATA_BASE_URL,
+    ADDYS_API_KEY: process.env.ADDYS_API_KEY ?? RAINBOW_DEMO_SERVICE_API_KEY,
+    ADDYS_BASE_URL: process.env.ADDYS_BASE_URL ?? RAINBOW_DEMO_METADATA_BASE_URL,
+    PLATFORM_API_KEY: process.env.PLATFORM_API_KEY ?? RAINBOW_DEMO_SERVICE_API_KEY,
+    PLATFORM_BASE_URL: process.env.PLATFORM_BASE_URL ?? RAINBOW_DEMO_METADATA_BASE_URL,
+    RAINBOW_MASTER_KEY: process.env.RAINBOW_MASTER_KEY ?? RAINBOW_DEMO_MASTER_KEY,
+    RAINBOW_RELAY_QUOTE_SIGNER:
+      process.env.RAINBOW_RELAY_QUOTE_SIGNER ?? RAINBOW_DEMO_QUOTE_SIGNER,
+    RAINBOW_RELAY_URL: process.env.RAINBOW_RELAY_URL ?? RAINBOW_DEMO_RELAY_URL,
+    RPC_PROXY_API_KEY_PROD: RAINBOW_DEMO_RPC_API_KEY,
+    RPC_PROXY_BASE_URL_PROD:
+      process.env.RAINBOW_RPC_PROXY_BASE_URL ??
+      process.env.RPC_PROXY_BASE_URL_PROD ??
+      RAINBOW_DEMO_RPC_PROXY_BASE_URL,
+    SECURE_WALLET_HASH_KEY:
+      process.env.SECURE_WALLET_HASH_KEY ?? RAINBOW_DEMO_SECURE_WALLET_HASH_KEY,
+  }
+
+  const optionalEnvVars = [
+    'ADDYS_API_KEY',
+    'ADDYS_BASE_URL',
+    'IMGIX_DOMAIN',
+    'IMGIX_TOKEN',
+    'PLATFORM_API_KEY',
+    'PLATFORM_BASE_URL',
+    'RAINBOW_TEST_WALLET',
+    'RAINBOW_RELAY_API_KEY',
+    'RAINBOW_RELAY_URL',
+    'SECURE_WALLET_HASH_KEY',
+    'TOKEN_SEARCH_URL',
+    'WC_PROJECT_ID',
+  ]
+
+  for (const key of optionalEnvVars) {
+    const value = process.env[key]
+    if (value) env[key] = value
+  }
+
+  if (!env.WC_PROJECT_ID && process.env.RAINBOW_WALLETCONNECT_PROJECT_ID) {
+    env.WC_PROJECT_ID = process.env.RAINBOW_WALLETCONNECT_PROJECT_ID
+  }
+
+  return env
+}
+
+function ensureRainbowDemoNetworks(): void {
+  if (!existsSync(RAINBOW_NETWORKS_FILE)) return
+
+  const payload = JSON.parse(readFileSync(RAINBOW_NETWORKS_FILE, 'utf8')) as {
+    networks?: Array<{
+      id?: string
+      defaultRPC?: {
+        url?: string
+      }
+    }>
+  }
+  if (!Array.isArray(payload.networks)) return
+
+  let changed = false
+  for (const network of payload.networks) {
+    const url = network.id ? RAINBOW_DEMO_PUBLIC_RPC_URLS[network.id] : undefined
+    if (!url || !network.defaultRPC) continue
+    if (network.defaultRPC.url === url) continue
+
+    network.defaultRPC.url = url
+    changed = true
+  }
+
+  if (changed) {
+    writeFileSync(RAINBOW_NETWORKS_FILE, `${JSON.stringify(payload)}\n`)
+  }
+}
+
+function ensureRainbowSetup(): void {
+  if (!existsSync(RAINBOW_DIR)) return
+
+  ensureRainbowGraphqlConfig()
+
+  if (!existsSync(join(RAINBOW_GRAPHQL_DIR, 'node_modules/.bin/graphql-codegen'))) {
+    runRainbowSetupCommand('fnm exec --using=22 yarn install', RAINBOW_GRAPHQL_DIR)
+  }
+
+  const missingGraphql = RAINBOW_GRAPHQL_SENTINELS.some(
+    (rel) => !existsSync(join(RAINBOW_DIR, rel)),
+  )
+  if (missingGraphql) {
+    runRainbowSetupCommand('fnm exec --using=22 yarn codegen', RAINBOW_GRAPHQL_DIR)
+  }
+
+  if (!existsSync(RAINBOW_NETWORKS_FILE)) {
+    runRainbowSetupCommand('fnm exec --using=22 yarn fetch:networks', RAINBOW_DIR)
+  }
+  ensureRainbowDemoNetworks()
+}
+
+const ARTSY_DIR = join(HOME, 'github/eigen')
+const ARTSY_KEYS_FILE = join(ARTSY_DIR, 'keys.shared.json')
+const ARTSY_METAFLAGS_FILE = join(ARTSY_DIR, 'metaflags.json')
+const ARTSY_RELAY_SENTINEL = join(ARTSY_DIR, 'src/__generated__/.relay-complete')
+
+function readArtsyKeysPayload():
+  | { secure?: Record<string, string>; public?: Record<string, unknown> }
+  | undefined {
+  if (!existsSync(ARTSY_KEYS_FILE)) return undefined
+
+  try {
+    const parsed = JSON.parse(readFileSync(ARTSY_KEYS_FILE, 'utf8')) as {
+      secure?: Record<string, string>
+      public?: Record<string, unknown>
+    }
+    if (!parsed || typeof parsed !== 'object') return undefined
+
+    const secure =
+      parsed.secure && typeof parsed.secure === 'object' ? parsed.secure : undefined
+    const publicKeys =
+      parsed.public && typeof parsed.public === 'object' ? parsed.public : undefined
+
+    if (!secure && !publicKeys) return undefined
+    return { secure, public: publicKeys }
+  } catch {
+    return undefined
+  }
+}
+
+function resolveArtsyRuntimeConfig(): SootSimConfig | undefined {
+  const email = process.env.SOOTSIM_ARTSY_EMAIL ?? process.env.MAESTRO_TEST_EMAIL
+  const password = process.env.SOOTSIM_ARTSY_PASSWORD ?? process.env.MAESTRO_TEST_PASSWORD
+  const keys = readArtsyKeysPayload()
+
+  const env: Record<string, string> = {}
+  if (email && password) {
+    env.SOOTSIM_LAUNCH_ARGUMENTS = JSON.stringify({
+      email,
+      password,
+      useMaestroInit: true,
+    })
+  }
+  if (keys) {
+    env.SOOTSIM_REACT_NATIVE_KEYS_JSON = JSON.stringify(keys)
+  }
+  if (Object.keys(env).length === 0) return undefined
+
+  return {
+    env,
+  }
+}
+
+function ensureArtsySetup(): void {
+  if (!existsSync(ARTSY_DIR)) return
+  const { execSync } =
+    require('node:child_process') as typeof import('node:child_process')
+
+  // yarn 4.10.3's bundled git cloner passes `-c core.autocrlf=false` as a
+  // single argv token, which git 2.53+ rejects with `invalid key: core.autocrlf`
+  // (note the leading space git sees after stripping `-c`). older gits
+  // silently tolerated the space. patch the release binary in-place to split
+  // the token. idempotent: replacement is a no-op after the first run.
+  const yarnRelease = join(ARTSY_DIR, '.yarn/releases/yarn-4.10.3.cjs')
+  if (existsSync(yarnRelease)) {
+    const src = readFileSync(yarnRelease, 'utf8')
+    const needle = '["clone","-c core.autocrlf=false",'
+    if (src.includes(needle)) {
+      writeFileSync(
+        yarnRelease,
+        src.replace(needle, '["clone","-c","core.autocrlf=false",'),
+      )
+    }
+  }
+
+  // install deps if the yarn state file is missing. use
+  // YARN_CHECKSUM_BEHAVIOR=update because the lockfile's hash for the
+  // `react-native-launch-arguments` git dep won't match archives produced
+  // after the clone-fix above (yarn recomputes tree hashes per fresh fetch).
+  if (!existsSync(join(ARTSY_DIR, 'node_modules/.yarn-state.yml'))) {
+    execSync('yarn install', {
+      cwd: ARTSY_DIR,
+      stdio: 'inherit',
+      env: { ...process.env, YARN_CHECKSUM_BEHAVIOR: 'update' },
+    })
+  }
+
+  // setup:oss creates keys.shared.json, metaflags.json, a phony
+  // GoogleService-Info.plist, and pulls OSS fonts. the aws font fetch fails
+  // without aws cli — harmless for a metro-only demo, fonts fall back.
+  if (!existsSync(ARTSY_KEYS_FILE) || !existsSync(ARTSY_METAFLAGS_FILE)) {
+    try {
+      execSync('yarn setup:oss', { cwd: ARTSY_DIR, stdio: 'inherit' })
+    } catch {
+      // setup-oss-fonts exits non-zero when `aws` is missing. ensure the
+      // two critical sentinel files exist before giving up.
+      if (!existsSync(ARTSY_KEYS_FILE) || !existsSync(ARTSY_METAFLAGS_FILE)) {
+        throw new Error('artsy demo: setup:oss did not create keys/metaflags')
+      }
+    }
+  }
+
+  // eigen pulls react-native-launch-arguments as a git dep. its package.json
+  // points `main` at `dist/index.js`, which is produced by the package's
+  // `prepare` tsc build — skipped because `.yarnrc.yml` sets
+  // `enableScripts: false`. there's no shipped tsconfig either, so running
+  // tsc post-hoc fails. simplest fix: point `main` at the TS source; metro
+  // resolves `.ts` natively. idempotent.
+  const rnlaPkgJson = join(
+    ARTSY_DIR,
+    'node_modules/react-native-launch-arguments/package.json',
+  )
+  if (existsSync(rnlaPkgJson)) {
+    const raw = readFileSync(rnlaPkgJson, 'utf8')
+    if (raw.includes('"dist/index.js"')) {
+      writeFileSync(rnlaPkgJson, raw.replace('"dist/index.js"', '"src/index.ts"'))
+    }
+  }
+
+  // relay compiler generates src/__generated__/**. eigen's `yarn start`
+  // script runs `relay-compiler --watch` via concurrently, but for the
+  // demo we just need a one-shot generation before metro boots.
+  if (!existsSync(ARTSY_RELAY_SENTINEL)) {
+    execSync('yarn relay', { cwd: ARTSY_DIR, stdio: 'inherit' })
+    writeFileSync(ARTSY_RELAY_SENTINEL, '')
+  }
+}
+
+export const APPS: DemoApp[] = [
+  {
+    name: 'bluesky',
+    label: 'Bluesky',
+    dir: join(HOME, 'github/bluesky'),
+    preferredPort: 8082,
+    framework: 'expo',
+    command: (p) => ({ cmd: `npx expo start --port ${p}` }),
+    credentials: {
+      envVars: ['SOOTSIM_BLUESKY_PASSWORD'],
+      known: { HANDLE: 'natew.bsky.social' },
+    },
+  },
+  {
+    name: '3pc',
+    label: '3PunchConvo',
+    dir: join(HOME, 'lightstrike-labs/three-punch-convo-app/apps/one'),
+    preferredPort: 8081,
+    framework: 'one',
+    command: (p) => ({ cmd: 'npx one dev', env: { ONE_PORT: String(p) } }),
+  },
+  {
+    name: 'uniswap',
+    label: 'Uniswap',
+    dir: UNISWAP_APP_DIR,
+    preferredPort: 8085,
+    framework: 'expo',
+    prepare: () => {
+      ensureUniswapDemoEnvLocal()
+      ensureUniswapForceUpgradePatched()
+    },
+    command: (p) => ({
+      cmd: `npx expo start --clear --port ${p}`,
+      // prefer the real local mobile env when present, otherwise fall back
+      // to Uniswap's checked-in public web RPC settings so demo boots cleanly.
+      env: resolveUniswapDemoEnv(),
+    }),
+  },
+  {
+    name: 'takeout',
+    label: 'Takeout',
+    dir: join(HOME, 'takeout'),
+    preferredPort: 8086,
+    framework: 'one',
+    // takeout needs more than Metro for the demo to actually work: better-auth
+    // (login), zero-cache (sync), and a postgres for both. `bun lite` brings
+    // up the orez-backed stack (PG + zero + s3 in one binary) plus the One
+    // dev server. takeout's env system shifts every port (web, pg, zero,
+    // minio) uniformly by PORT_OFFSET, so we derive offset = port - 8081
+    // (the base web port) to keep all backend ports clear of the default
+    // dev stack while pinning One to the demo slot. OREZ_DATA_DIR is isolated
+    // to a per-demo path so we don't fight a soot dev orez that may already
+    // be holding pglite locks on ~/takeout/.orez (soot can attach takeout as
+    // a project and spin up its own orez against the same data dir).
+    readyTimeoutMs: 240_000,
+    command: (p) => ({
+      cmd: 'bun lite',
+      env: {
+        PORT_OFFSET: String(p - 8081),
+        OREZ_DATA_DIR: `${HOME}/.cache/sootsim-demo/takeout-orez`,
+      },
+    }),
+  },
+  {
+    name: 'expensify',
+    label: 'Expensify',
+    dir: join(HOME, 'github/expensify'),
+    preferredPort: 8087,
+    framework: 'rock',
+    runtimeConfig: {
+      env: EXPENSIFY_NATIVE_PROXY_ENV,
+    },
+    sidecars: [
+      {
+        name: 'web-proxy',
+        port: 9000,
+        readyPath: '/api/Ping',
+        command: () => ({
+          cmd: `bun ${JSON.stringify(getExpensifyProxyScript())}`,
+          env: EXPENSIFY_NATIVE_PROXY_ENV,
+        }),
+      },
+    ],
+    command: (p) => ({
+      cmd: `fnm exec --using=20.20.0 npx rock start --port ${p} --no-interactive`,
+      env: EXPENSIFY_NATIVE_PROXY_ENV,
+    }),
+  },
+  {
+    name: 'artsy',
+    label: 'Artsy',
+    dir: ARTSY_DIR,
+    preferredPort: 8088,
+    framework: 'expo',
+    runtimeConfig: resolveArtsyRuntimeConfig(),
+    prepare: () => {
+      ensureArtsySetup()
+    },
+    command: (p) => ({
+      // eigen's `yarn start` wraps `react-native start` with a relay watcher
+      // via concurrently; for the demo we run relay once in prepare and
+      // invoke the metro server directly so --port is respected.
+      cmd: `npx react-native start --port ${p}`,
+    }),
+    credentials: {
+      envVars: ['SOOTSIM_ARTSY_EMAIL', 'SOOTSIM_ARTSY_PASSWORD'],
+      note: 'auto-login reuses Artsy’s built-in Maestro launch-arguments hook',
+    },
+  },
+  {
+    name: 'rainbow',
+    label: 'Rainbow',
+    dir: RAINBOW_DIR,
+    preferredPort: 8089,
+    framework: 'rock',
+    sidecars: [
+      {
+        name: 'metadata-proxy',
+        port: RAINBOW_METADATA_PROXY_PORT,
+        readyPath: '/health',
+        command: () => ({
+          cmd: `bun ${JSON.stringify(getRainbowMetadataProxyScript())}`,
+          env: {
+            PORT: String(RAINBOW_METADATA_PROXY_PORT),
+            RAINBOW_PUBLIC_RPC_URLS: JSON.stringify(RAINBOW_DEMO_PUBLIC_RPC_URLS),
+            RAINBOW_UPSTREAM_METADATA_BASE_URL: RAINBOW_METADATA_BASE_URL,
+          },
+        }),
+      },
+    ],
+    prepare: () => {
+      ensureRainbowSetup()
+    },
+    command: (p) => ({
+      cmd: `fnm exec --using=22 yarn start --port ${p} --reset-cache`,
+      env: resolveRainbowDemoEnv(),
+    }),
+    credentials: {
+      envVars: [
+        'RAINBOW_TEST_WALLET',
+        'RAINBOW_WALLETCONNECT_PROJECT_ID',
+        'WC_PROJECT_ID',
+        'IMGIX_DOMAIN',
+        'IMGIX_TOKEN',
+      ],
+      note: 'launcher supplies a demo encryption key and public mainnet RPC; use only a public throwaway mnemonic for RAINBOW_TEST_WALLET',
+    },
+  },
+  {
+    name: 'rocket-chat',
+    label: 'Rocket.Chat',
+    dir: join(HOME, 'github/Rocket.Chat.ReactNative'),
+    preferredPort: 8093,
+    framework: 'expo',
+    command: (p) => ({
+      cmd: `npx react-native start --port ${p}`,
+      env: { RUNNING_E2E_TESTS: 'true' },
+    }),
+    credentials: {
+      envVars: [
+        'ROCKET_CHAT_DEMO_SERVER',
+        'ROCKET_CHAT_DEMO_USERNAME',
+        'ROCKET_CHAT_DEMO_PASSWORD',
+      ],
+      known: { SERVER: 'https://mobile.qa.rocket.chat' },
+      note: 'use packages/sootsim-engine/scripts/rocket-chat-demo-auth.ts to create/login a disposable QA user and print the rocketchat://auth deep link',
+    },
+  },
+  {
+    name: 'mattermost',
+    label: 'Mattermost',
+    dir: MATTERMOST_DIR,
+    preferredPort: 8090,
+    framework: 'expo',
+    sidecars: [
+      {
+        name: 'preview-server',
+        port: 8065,
+        readyPath: '/api/v4/system/ping',
+        command: () => ({
+          cmd: `bun ${JSON.stringify(getMattermostPreviewServerScript())}`,
+        }),
+      },
+    ],
+    runtimeConfig: {
+      modules: {
+        // mattermost patches react-native-keychain's JS entry in its own
+        // repo; run that package and provide only the native manager seam.
+        'react-native-keychain': false,
+        'dist/assets/config.json': {
+          inline: {
+            AuthUrlScheme: 'mmauth://',
+            AuthUrlSchemeDev: 'mmauthbeta://',
+            DefaultServerUrl: 'http://localhost:8065',
+            DefaultServerName: 'Mattermost Demo',
+            TestServerUrl: 'http://localhost:8065',
+            AutoSelectServerUrl: true,
+            WebsiteURL: 'https://mattermost.com',
+            ServerNoticeURL:
+              'https://github.com/mattermost/mattermost-server/blob/master/NOTICE.txt',
+            MobileNoticeURL:
+              'https://github.com/mattermost/mattermost-mobile/blob/master/NOTICE.txt',
+            RudderApiKey: '',
+            SentryEnabled: false,
+            SentryDsnIos: '',
+            SentryDsnAndroid: '',
+            SentryOptions: {
+              deactivateStacktraceMerging: true,
+              autoBreadcrumbs: {
+                xhr: false,
+                console: true,
+              },
+              severityLevelFilter: ['fatal'],
+            },
+            ShowReview: false,
+            ShowOnboarding: false,
+            ExperimentalNormalizeMarkdownLinks: false,
+            CustomRequestHeaders: {},
+            CollectNetworkMetrics: false,
+          },
+        },
+      },
+      nativeModules: {
+        RNKeychainManager: { file: getMattermostKeychainNativeModule() },
+        RNUtils: { file: getMattermostRNUtilsNativeModule() },
+        GenericClient: { file: getMattermostNetworkClientNativeModule() },
+        ApiClient: { file: getMattermostNetworkClientNativeModule() },
+        WebSocketClient: { file: getMattermostNetworkClientNativeModule() },
+      },
+    },
+    command: (p) => ({
+      cmd: `npx react-native start --host 127.0.0.1 --port ${p}`,
+    }),
+    credentials: {
+      known: {
+        SERVER: 'http://localhost:8065',
+        USERNAME: 'demo',
+        PASSWORD: 'DemoPassword1!',
+      },
+      note: 'local mattermost-preview seeded through the real REST API; no signup or OTP needed',
+    },
+  },
+  {
+    name: 'joplin',
+    label: 'Joplin',
+    dir: JOPLIN_APP_DIR,
+    preferredPort: 8084,
+    framework: 'expo',
+    // joplin is local-first: sync.target defaults to 0 ("None") and the
+    // mobile startup runs WelcomeUtils.install() on first launch, which
+    // seeds a "Welcome!" folder + welcome notes. no login or external
+    // credentials are needed for a usable demo — just boot it. tenant
+    // bedrock SQLite (via react-native-sqlite-storage stub) carries the
+    // seeded notes across reloads.
+    prepare: () => {
+      ensureJoplinWatchmanConfigs()
+      ensureJoplinBuilt()
+    },
+    command: (p) => ({
+      cmd: `npx expo start --port ${p}`,
+      env: { BROWSERSLIST_IGNORE_OLD_DATA: 'true' },
+    }),
+    credentials: {
+      note: 'no login required — sync.target=0 (None), seed via WelcomeUtils',
+    },
+  },
+]