peachsim 0.1.1481 → 0.1.1594

package/README.md

@@ -185,6 +185,12 @@ config dictionary is empty and the app can select its own public defaults.
 Preserve failures from those endpoints rather than remapping them to a successful
 local response. The same flag is available on `peach flow`.
 
+A project with several Xcode application targets names the one to run, as an
+Xcode scheme does: `peach open <app-port> --ios-target <name>` (also on
+`peach flow` and `peach maestro test`) reads that target's version, build,
+bundle id and display name. Without it, such an app served by a plain Metro
+reads the runtime defaults.
+
 **The daemon is one process** — `SootSimBridgeHost` (`src/host/bridge-host.ts`).
 `peach serve` runs it in the foreground; the background daemon is the *same
 process* wrapped with autostart and the `~/.peach/daemon.json` lockfile. It is
@@ -196,6 +202,12 @@ guest-app fetch/WebSocket traffic so the cross-origin tenant worker can reach
 localhost. The `AgentHost` extension owns one FIFO reader per agent session and
 fans agent events out to every subscriber.
 
+`peach open` auto-installs a published runtime only when the runtime directory
+is empty. If runtime files exist without a selected runtime containing
+`index.html`, it refuses to open. Finish copying the runtime, then select it
+with `peach runtime use <version>`. Write the active marker after staging is
+complete when preparing an isolated home.
+
 During source development, each Vite bridge owns one
 `~/.peach/dev-bridges/<port>.json` heartbeat record. CLI defaults select the
 current `PORT_OFFSET`, then the current checkout, then the canonical `:7668`
@@ -267,6 +279,7 @@ therefore runs before assertions in each flow.
 curl -fsSL https://peachsim.com/install.sh | sh   # or: npx peachsim
 peach                 # open ConnectRN and choose a running app in the simulator
 peach open /settings  # dispatch a React Native deep link into that app
+peach open /settings --no-describe --quiet  # keep open options with deep links
 ```
 
 Start Metro, Expo, One, or another supported React Native development server
@@ -389,6 +402,8 @@ outside `node_modules`, `dist`, and `build`. Keep it before
 `react-native-worklets/plugin` in a custom Babel stack that lists both plugins.
 Apps using `babel-preset-expo` omit the explicit Worklets plugin because the
 preset configures it automatically.
+Runtime Fragment aliases are excluded before element creation. Component tag
+expressions are evaluated once, and ordinary components retain their locations.
 
 For One's Rolldown native bundler, use the native transform in `vite.config.ts`:
 
@@ -421,7 +436,7 @@ peach open 8081         # load a running metro/expo dev server
 peach open /settings    # route via React Native Linking
 peach describe          # dump UI tree
 peach get errors 5      # recent runtime failures
-peach compat            # scan native package compatibility
+peach doctor            # check what of this app Peach runs
 peach support report "…"  # preview an opt-in compatibility report
 peach find --testid cta # inspect one node deeply
 peach debug enable animated,layout
@@ -499,6 +514,11 @@ options and enables two integrations:
 The URL helpers request ordinary Metro graphs: `dev=false&minify=true` for
 production and `dev=true&minify=false` for development.
 
+Metro registration readers retain the original factory bytes and module IDs.
+Empty dependencies may be an empty array, an omitted production argument, or a
+null development argument before the module name. Identity validation and
+fingerprinting treat each as zero dependencies and reject malformed arguments.
+
 ```js
 const {
   toPeachProductionBundleUrl,
@@ -695,11 +715,11 @@ serves its selected version from a version-specific localhost origin, so a
 background activation cannot mix an already loaded shell with chunks from the
 next runtime. Without config, each new open selects the active stable version.
 When `peach.config.ts` sets `runtimeVersion`, `peach open` installs that
-version without changing the machine default. The same file replaces an app's own
-native modules (`nativeModules`, `turboModules`) and native views
-(`nativeViews`, keyed by the `requireNativeComponent` name or an Expo view's
-`Module_View` name) with project-local files; the configuration guide in the
-docs lists every slot. App config, native-linked fonts,
+version without changing the machine default. The same file answers native code Peach does
+not know under `packages`, keyed by the package and then its native module
+and view names, and an installed `peach-stub-<package>` package answers in the
+same shape with no config line; the configuration guide in the docs lists
+every slot. App config, native-linked fonts,
 and splash assets resolve from the local directory named by `--project-root`
 when supplied, otherwise the project root advertised by the selected development
 server. Hosted recorders pass their checked-out repository explicitly because

package/cli/app-config.ts

@@ -4,6 +4,7 @@ import * as peachConfigModule from '../src/config'
 import { isPeachConfig, type PeachConfig } from '../src/config'
 import { rnxPublicBrand } from '../src/public-brand'
 import { resolveAppProject, type ResolvedAppProject } from './app-project'
+import { resolveAppStubs, type AppStubs } from './app-stubs'
 
 // `{ file }` entries are relative to the config file; the engine loads them by
 // absolute path from the runtime's replacement-module endpoint.
@@ -33,16 +34,42 @@ function resolveConfigReplacementFiles(
   return {
     ...config,
     modules: resolveFileEntries(config.modules, configDir),
-    turboModules: resolveFileEntries(config.turboModules, configDir),
-    nativeModules: resolveFileEntries(config.nativeModules, configDir),
-    nativeViews: resolveFileEntries(config.nativeViews, configDir),
   }
 }
 
+// the engine's wire slots; an app names native stubs by package instead
+const WIRE_SLOTS = ['nativeModules', 'turboModules', 'nativeViews'] as const
+
+// the app's config with every native stub lowered into the engine's wire slots:
+// its own `packages` and the installed stub packages, applied with or without
+// a peach.config.ts.
 export async function loadRNXAppConfig(
   project: ResolvedAppProject | null,
 ): Promise<PeachConfig | undefined> {
-  if (!project?.configPath) return undefined
+  return (await loadRNXAppStubs(project)).config
+}
+
+export async function loadRNXAppStubs(
+  project: ResolvedAppProject | null,
+): Promise<{ config: PeachConfig | undefined; stubs: AppStubs }> {
+  if (!project) return { config: undefined, stubs: { applied: [], skipped: [] } }
+  const config = await loadConfigFile(project)
+  try {
+    return resolveAppStubs(
+      project.appDir,
+      config,
+      project.configPath ? path.dirname(project.configPath) : project.appDir,
+    )
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`could not load the native stubs of ${project.appDir}: ${message}`)
+  }
+}
+
+async function loadConfigFile(
+  project: ResolvedAppProject,
+): Promise<PeachConfig | undefined> {
+  if (!project.configPath) return undefined
   try {
     const jiti = createJiti(import.meta.url, {
       interopDefault: true,
@@ -57,6 +84,12 @@ export async function loadRNXAppConfig(
     if (!isPeachConfig(loaded)) {
       throw new Error('the default export must be a peach config object')
     }
+    const wire = WIRE_SLOTS.filter((slot) => loaded[slot] !== undefined)
+    if (wire.length > 0) {
+      throw new Error(
+        `${wire.join(', ')} moved under packages, keyed by the package whose native side they answer: packages: { 'package-name': { modules: { Name: './stub.ts' }, views: { Name: './View.tsx' } } }`,
+      )
+    }
     return resolveConfigReplacementFiles(loaded, project.configPath)
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
@@ -64,9 +97,11 @@ export async function loadRNXAppConfig(
   }
 }
 
-export async function resolveRNXAppConfig(
-  startDir: string = process.cwd(),
-): Promise<{ project: ResolvedAppProject | null; config: PeachConfig | undefined }> {
+export async function resolveRNXAppConfig(startDir: string = process.cwd()): Promise<{
+  project: ResolvedAppProject | null
+  config: PeachConfig | undefined
+  stubs: AppStubs
+}> {
   const project = resolveAppProject(startDir)
-  return { project, config: await loadRNXAppConfig(project) }
+  return { project, ...(await loadRNXAppStubs(project)) }
 }

package/cli/app-fonts.ts

@@ -3,10 +3,12 @@ import fs from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import {
+  encodeAppFontsWire,
   expoFontPathsFromPlugins,
   nativeLinkedFontSpecsFromPaths,
   metroFontSpecsFromPaths,
   type ConfigPluginFontSpec,
+  type FontPlatform,
 } from 'peach-engine/engine/config-plugin-fonts'
 import { resolveListeningPid, resolveProcessCwd } from '../scripts/dev-server-scanner'
 import { loopbackOriginOf } from '../src/backend-origin'
@@ -34,15 +36,17 @@ export function discoverNativeLinkedAppFonts(opts: {
 }): DiscoveredAppFontSpec[] {
   const metroOrigin = loopbackOriginOf(opts.bundleUrl)
   if (!metroOrigin) return []
-  const specs = metroFontSpecsFromPaths(
+  return metroFontSpecsFromPaths(
     projectRelativeFontPaths(opts.projectDir, discoverNativeLinkedAppFontPaths(opts)),
     metroOrigin,
+    nativeFontPlatform(opts.platform),
   )
-  // a family linked from more than one file keeps the first declaration.
-  const byFamily = new Map<string, DiscoveredAppFontSpec>()
-  for (const spec of specs)
-    if (!byFamily.has(spec.family)) byFamily.set(spec.family, spec)
-  return [...byFamily.values()]
+}
+
+function nativeFontPlatform(platform: string | undefined): FontPlatform {
+  return (platform || process.env.CONTRAST_PLATFORM || 'ios').toLowerCase() === 'android'
+    ? 'android'
+    : 'ios'
 }
 
 function projectRelativeFontPaths(projectDir: string, fontPaths: string[]): string[] {
@@ -68,7 +72,7 @@ function discoverNativeLinkedAppFontPaths(opts: {
   const selectedAppDir = project?.appDir ?? null
   if (!selectedAppDir) return []
 
-  const platform = (opts.platform || process.env.CONTRAST_PLATFORM || 'ios').toLowerCase()
+  const platform = nativeFontPlatform(opts.platform)
 
   let getConfig: ExpoConfigGetter | null = null
   // resolve from the exact app root advertised by the development server.
@@ -97,10 +101,7 @@ function discoverNativeLinkedAppFontPaths(opts: {
   }
 
   // a declared path with no file behind it links nothing natively.
-  const fontPaths = expoFontPathsFromPlugins(
-    plugins,
-    platform === 'android' ? 'android' : 'ios',
-  )
+  const fontPaths = expoFontPathsFromPlugins(plugins, platform)
     .slice(0, 256)
     .map((fontPath) => path.resolve(selectedAppDir, fontPath))
     .filter(isFile)
@@ -285,6 +286,7 @@ export function readNativeLinkedAppFontsWire(opts: {
   return encodeAppFontsWire(
     nativeLinkedFontSpecsFromPaths(
       projectRelativeFontPaths(opts.projectDir, discoverNativeLinkedAppFontPaths(opts)),
+      nativeFontPlatform(opts.platform),
       (fontPath) => {
         const bytes = fs.readFileSync(path.resolve(opts.projectDir, fontPath))
         return `data:${fontContentType(fontPath)};base64,${bytes.toString('base64')}`
@@ -355,12 +357,6 @@ export async function resolveMetroProjectRoot(bundleUrl: string): Promise<string
   return pid === null ? null : resolveProcessCwd(pid)
 }
 
-export function encodeAppFontsWire(specs: DiscoveredAppFontSpec[]): string {
-  return specs
-    .map((spec) => `${encodeURIComponent(spec.url)}::${encodeURIComponent(spec.family)}`)
-    .join(',')
-}
-
 export function parseAppFontUrls(wire: string): string[] {
   const urls: string[] = []
   for (const entry of wire.split(',')) {

package/cli/app-stubs.ts

@@ -0,0 +1,302 @@
+// native stubs keyed by the package they answer (specs/peach-app-stubs.md):
+// the app's peach.config.ts `packages`, installed `peach-stub-<package>`
+// packages, and a library's own `peach` field, lowered into the engine's
+// nativeModules / nativeViews wire slots.
+
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { resolveCompatVersionRange } from '@peach/compat/version-range'
+import {
+  isPackageStubs,
+  type NativeModuleResolution,
+  type NativeStub,
+  type NativeViewResolution,
+  type PackageStubs,
+  type PeachConfig,
+} from '../src/config'
+import { isRecord } from '../src/is-record'
+import { readProjectManifest, scanRepository } from './commands/detect'
+
+// who answers a package, in rising precedence
+export type StubOrigin = 'library' | 'stub-package' | 'config'
+
+export interface AppliedStubs {
+  target: string
+  origin: StubOrigin
+  // the package declaring the stubs; null for peach.config.ts
+  provider: string | null
+  providerVersion: string | null
+  modules: string[]
+  views: string[]
+}
+
+// a published stub whose `versions` range excludes the installed target
+export interface SkippedStubs {
+  target: string
+  provider: string
+  providerVersion: string | null
+  versions: string
+  installed: string
+}
+
+export interface AppStubs {
+  applied: AppliedStubs[]
+  skipped: SkippedStubs[]
+}
+
+interface StubSource {
+  target: string
+  origin: StubOrigin
+  provider: string | null
+  providerVersion: string | null
+  stubs: PackageStubs
+  // where relative stub paths resolve from
+  baseDir: string
+}
+
+// `peach-stub-<package>` or `@scope/peach-stub-<package>`; a scoped target uses
+// the DefinitelyTyped encoding, `@acme/scanner` as `peach-stub-acme__scanner`.
+export function stubPackageTarget(name: string): string | null {
+  const match = /^(?:@[^/]+\/)?peach-stub-(.+)$/.exec(name)
+  if (!match?.[1]) return null
+  const split = match[1].indexOf('__')
+  return split > 0
+    ? `@${match[1].slice(0, split)}/${match[1].slice(split + 2)}`
+    : match[1]
+}
+
+export function resolveAppStubs(
+  appDir: string,
+  config: PeachConfig | undefined,
+  configDir: string,
+): { config: PeachConfig | undefined; stubs: AppStubs } {
+  const sources: StubSource[] = []
+  const skipped: SkippedStubs[] = []
+  const manifest = readProjectManifest(appDir)
+  for (const name of Object.keys({
+    ...manifest?.devDependencies,
+    ...manifest?.dependencies,
+  })) {
+    const dir = installedPackageDir(appDir, name)
+    const installed = dir ? readPackageJson(dir) : null
+    if (!dir || !installed || installed.peach === undefined) continue
+    const stubTarget = stubPackageTarget(name)
+    const target = stubTarget ?? name
+    const field = installed.peach
+    const versions = isRecord(field) ? field.versions : undefined
+    const stubs = isRecord(field) ? { modules: field.modules, views: field.views } : field
+    if (
+      !isPackageStubs(stubs) ||
+      (versions !== undefined && typeof versions !== 'string')
+    )
+      throw new Error(
+        `${name}'s package.json "peach" field must be "noop" or { versions?, modules?, views? } whose values are "noop" or file paths`,
+      )
+    const providerVersion =
+      typeof installed.version === 'string' ? installed.version : null
+    const targetDir = stubTarget ? installedPackageDir(appDir, target) : dir
+    const targetVersion = targetDir ? readPackageJson(targetDir)?.version : undefined
+    // a stub for a package the app does not install answers nothing
+    if (typeof targetVersion !== 'string') continue
+    if (
+      versions !== undefined &&
+      resolveCompatVersionRange([versions], targetVersion).status !== 'matched'
+    ) {
+      skipped.push({
+        target,
+        provider: name,
+        providerVersion,
+        versions,
+        installed: targetVersion,
+      })
+      continue
+    }
+    sources.push({
+      target,
+      origin: stubTarget ? 'stub-package' : 'library',
+      provider: name,
+      providerVersion,
+      stubs,
+      baseDir: dir,
+    })
+  }
+  for (const [target, stubs] of Object.entries(config?.packages ?? {})) {
+    sources.push({
+      target,
+      origin: 'config',
+      provider: null,
+      providerVersion: null,
+      stubs,
+      baseDir: configDir,
+    })
+  }
+
+  const ORDER: Record<StubOrigin, number> = { library: 0, 'stub-package': 1, config: 2 }
+  sources.sort((a, b) => ORDER[a.origin] - ORDER[b.origin])
+  const nativeModules: Record<string, NativeModuleResolution> = {}
+  const nativeViews: Record<string, NativeViewResolution> = {}
+  const applied: AppliedStubs[] = []
+  for (const source of sources) {
+    const { modules, views } = expandStubs(appDir, source)
+    for (const [name, stub] of Object.entries(modules))
+      nativeModules[name] = lowerStub(stub, source.baseDir)
+    for (const [name, stub] of Object.entries(views))
+      nativeViews[name] = lowerStub(stub, source.baseDir)
+    applied.push({
+      target: source.target,
+      origin: source.origin,
+      provider: source.provider,
+      providerVersion: source.providerVersion,
+      modules: Object.keys(modules),
+      views: Object.keys(views),
+    })
+  }
+  const stubs = { applied, skipped }
+  if (!config && applied.length === 0) return { config, stubs }
+  const lowered: PeachConfig = { ...config, nativeModules, nativeViews }
+  delete lowered.packages
+  return { config: lowered, stubs }
+}
+
+// a whole-package 'noop' answers every native name the installed package asks for
+function expandStubs(
+  appDir: string,
+  source: StubSource,
+): { modules: Record<string, NativeStub>; views: Record<string, NativeStub> } {
+  if (source.stubs !== 'noop')
+    return { modules: source.stubs.modules ?? {}, views: source.stubs.views ?? {} }
+  const dir = installedPackageDir(appDir, source.target)
+  if (!dir)
+    throw new Error(
+      `packages['${source.target}']: 'noop' answers the names an installed package asks for, and ${source.target} is not installed`,
+    )
+  const modules: Record<string, NativeStub> = {}
+  const views: Record<string, NativeStub> = {}
+  for (const request of packageNativeRequests(dir)) {
+    if (request.kind === 'module') modules[request.name] = 'noop'
+    else views[request.name] = 'noop'
+  }
+  return { modules, views }
+}
+
+function lowerStub(stub: NativeStub, baseDir: string): 'noop' | { file: string } {
+  return stub === 'noop' ? stub : { file: resolve(baseDir, stub) }
+}
+
+function readPackageJson(dir: string): Record<string, unknown> | null {
+  const text = readSmallFile(join(dir, 'package.json'))
+  if (!text) return null
+  try {
+    const parsed: unknown = JSON.parse(text)
+    return isRecord(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+// the installed copy of a dependency, found the way node resolves it
+export function installedPackageDir(appDir: string, name: string): string | null {
+  let current = appDir
+  while (true) {
+    const dir = join(current, 'node_modules', name)
+    if (existsSync(join(dir, 'package.json'))) return realpathSync(dir)
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+export interface NativeRequest {
+  kind: 'module' | 'view'
+  name: string
+}
+
+export const SOURCE_FILE = /\.[cm]?[jt]sx?$/
+export const NATIVE_LOOKUP = /requireNative|TurboModuleRegistry|codegenNativeComponent/
+// a requireNativeView(module, view) name is `module_view`, the key the engine
+// registers expo views under.
+export const LOOKUPS: { kind: NativeRequest['kind']; pattern: RegExp }[] = [
+  {
+    kind: 'view',
+    pattern: /\brequireNativeComponent\s*(?:<[^;]{0,200}?>)?\(\s*['"]([\w$.-]+)['"]/g,
+  },
+  {
+    kind: 'view',
+    pattern:
+      /\brequireNativeView(?:Manager)?\s*(?:<[^;]{0,200}?>)?\(\s*['"](\w+)['"]\s*(?:,\s*['"](\w+)['"])?/g,
+  },
+  {
+    kind: 'view',
+    pattern: /\bcodegenNativeComponent\s*(?:<[^;]{0,200}?>)?\(\s*['"](\w+)['"]/g,
+  },
+  {
+    kind: 'module',
+    pattern:
+      /\brequire(?:Optional)?NativeModule\s*(?:<[^;]{0,200}?>)?\(\s*['"](\w+)['"]/g,
+  },
+  {
+    kind: 'module',
+    pattern:
+      /\bTurboModuleRegistry\.get(?:Enforcing)?\s*(?:<[^;]{0,200}?>)?\(\s*['"](\w+)['"]/g,
+  },
+]
+
+// the native names a package's own JavaScript asks for, outside its native
+// sources (top-level ios and android; src/ios is JavaScript), tests and examples
+const NATIVE_SOURCE_DIRS = new Set(['ios', 'android'])
+const PACKAGE_SKIP_DIRS = new Set([
+  'example',
+  'examples',
+  '__tests__',
+  '__mocks__',
+  'docs',
+])
+const LEGACY_NATIVE_MODULE = /\bNativeModules\s*\.\s*(\w+)/g
+
+export function packageNativeRequests(dir: string): NativeRequest[] {
+  const found = new Map<string, NativeRequest>()
+  const directories = scanRepository(dir).directories.filter((sub) => {
+    const segments = relative(dir, sub).split('/')
+    return (
+      !NATIVE_SOURCE_DIRS.has(segments[0]) &&
+      !segments.some((segment) => PACKAGE_SKIP_DIRS.has(segment))
+    )
+  })
+  let files = 0
+  for (const sub of directories) {
+    for (const name of listDir(sub)) {
+      if (!SOURCE_FILE.test(name) || name.endsWith('.d.ts') || files >= 2_000) continue
+      files++
+      const text = readSmallFile(join(sub, name))
+      if (!text || !(NATIVE_LOOKUP.test(text) || text.includes('NativeModules'))) continue
+      for (const { kind, pattern } of [
+        ...LOOKUPS,
+        { kind: 'module' as const, pattern: LEGACY_NATIVE_MODULE },
+      ]) {
+        for (const match of text.matchAll(pattern)) {
+          const request = match[2] ? `${match[1]}_${match[2]}` : match[1]
+          if (request) found.set(`${kind}:${request}`, { kind, name: request })
+        }
+      }
+    }
+  }
+  return [...found.values()].sort(
+    (a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name),
+  )
+}
+
+export function listDir(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+export function readSmallFile(file: string): string | null {
+  try {
+    return statSync(file).size <= 1024 * 1024 ? readFileSync(file, 'utf8') : null
+  } catch {
+    return null
+  }
+}

package/cli/bin.ts

@@ -53,9 +53,13 @@ if (process.argv[2] === '__cloud-confirm') {
 // work does. so this is the branch that must skip the CLI rather than the CLI
 // that must skip it.
 const forkedScript = process.argv[2]
-if (process.env[RNX_FORKED_SCRIPT_ENV] === '1' && forkedScript?.endsWith('.js')) {
+if (
+  process.env[RNX_FORKED_SCRIPT_ENV] === '1' &&
+  forkedScript &&
+  /\.(?:c|m)?js$/.test(forkedScript)
+) {
   const { runScript } = await import('./internal-child')
-  runScript(forkedScript, process.argv.slice(3))
+  await runScript(forkedScript, process.argv.slice(3))
 } else if (process.argv[2] === RNX_INTERNAL_COMMAND) {
   const { runInternalChild } = await import('./internal-child')
   await runInternalChild(process.argv.slice(3))