peachsim 0.1.630 → 0.1.632

package/cli/commands/test.ts

@@ -455,6 +455,24 @@ function collectFlowHelperPaths(flowAbsPath: string): string[] {
   return helpers
 }
 
+// a synthesized workspace config that selects exactly one flow. bun's glob
+// (node:fs.globSync, which the planner reads) treats * ? [ ] { } as special
+// and has no backslash escape, so each is wrapped in a one-character class; a
+// leading `!` would negate the pattern, so it is anchored under ./.
+function selectionConfig(entryKey: string): string {
+  if (entryKey.includes('\\')) {
+    throw new Error(
+      `cloud test cannot select a flow whose path contains a backslash: ${entryKey}`,
+    )
+  }
+  const escaped = entryKey.replace(/[*?[\]{}]/g, (char) => `[${char}]`)
+  const glob = escaped.startsWith('!') ? `./${escaped}` : escaped
+  return (
+    '# synthesized by peach test --cloud: run exactly the submitted entry flow.\n' +
+    `flows:\n  - ${JSON.stringify(glob)}\n`
+  )
+}
+
 function collectTestFiles(
   targetPath: string,
   ignoredPath: string | null,
@@ -522,17 +540,14 @@ function collectTestFiles(
       // the recorder runs an unpacked multi-file upload as a workspace,
       // whose default glob only sees top-level flows: a nested entry would
       // lose to a top-level helper. pin a config that selects the entry.
-      if (!keys.some((key) => /^config\.ya?ml$/.test(basename(key)))) {
+      if (!keys.some((key) => /^config\.ya?ml$/.test(key))) {
         if (Object.keys(files).length >= RNX_CLOUD_TEST_FILES_MAX_COUNT) {
           throw new Error(
             `cloud test suites may contain at most ${RNX_CLOUD_TEST_FILES_MAX_COUNT} files`,
           )
         }
         const entryKey = keys[0] as string
-        const glob = entryKey.replace(/[\\*?[\]{}()!+@]/g, '\\$&')
-        files['config.yaml'] =
-          '# synthesized by peach test --cloud: run exactly the submitted entry flow.\n' +
-          `flows:\n  - ${JSON.stringify(glob)}\n`
+        files['config.yaml'] = selectionConfig(entryKey)
       }
     }
     for (const configName of [
@@ -682,11 +697,16 @@ export async function runCloudTest(
     return 1
   }
 
-  const targetPath = resolve(process.cwd(), target)
+  let targetPath = resolve(process.cwd(), target)
   if (!existsSync(targetPath)) {
     console.error(`  error: test target not found: ${target}`)
     return 1
   }
+  // a file literally named config.yaml names a workspace, not a flow: local
+  // dispatch runs its directory, so hosted planning does too.
+  if (statSync(targetPath).isFile() && /^config\.ya?ml$/.test(basename(targetPath))) {
+    targetPath = dirname(targetPath)
+  }
 
   if (!app) {
     console.error(
@@ -798,21 +818,163 @@ export async function runCloudTest(
     app.includes('/api/preview/share/bundle')
       ? null
       : resolve(process.cwd(), app)
-  const testFiles = collectTestFiles(collectionPath, localBundlePath)
-  if (Object.keys(testFiles).length === 0) {
-    console.error(`  error: no test files found at ${target}`)
+
+  // one hosted job per Maestro flow. a suite whose total executor time passes
+  // the 45 minute per-job cap still completes when every flow stays under it,
+  // so a directory target uploads the whole original file set (flows and
+  // helpers byte-identical) plus a synthesized config selecting one flow per
+  // job. tag selection resolves here, before any submission, exactly as a
+  // local workspace run resolves it: the CLI planner reads the workspace
+  // config, applies CLI include/exclude overrides, and the selected flows are
+  // the jobs. the jobs run one at a time because live sidecars can share
+  // mutable backend state. detox suites and explicit single flows keep their
+  // existing one-job whole-suite path.
+  const jobs: Array<{
+    label: string | null
+    testFiles: Record<string, string>
+    testArgs: string[] | null
+  }> = []
+  const hasConfig = forwarded.some(
+    (arg) => arg === '--config' || arg.startsWith('--config='),
+  )
+  const maestroConfig = hasConfig && isMaestroConfigValue(config)
+  const maestroTarget = (() => {
+    if (hasConfig && !maestroConfig) return false
+    if (!statSync(targetPath).isDirectory()) {
+      return /\.ya?ml$/.test(extname(targetPath))
+    }
+    return (
+      readdirSync(targetPath).some((name) => /\.ya?ml$/.test(name)) ||
+      ['.maestro', 'maestro'].includes(basename(targetPath))
+    )
+  })()
+  if (
+    !maestroTarget &&
+    (cloudTestArgs ?? []).some(
+      (arg) =>
+        arg === '--env' ||
+        arg === '-e' ||
+        arg.startsWith('--env=') ||
+        arg.startsWith('-e='),
+    )
+  ) {
+    console.error(
+      '  error: --env supplies maestro flow variables and requires a maestro target',
+    )
     return 1
   }
+  if (maestroTarget) {
+    // maestro has no test-name or test-path selection; the cloud selector
+    // vocabulary is shared with detox, so a jest selector here is refused
+    // before submission rather than silently dropped from the hosted job.
+    const unsupported = (cloudTestArgs ?? []).filter((arg) => {
+      const eq = arg.indexOf('=')
+      const head = eq > 0 ? arg.slice(0, eq) : arg
+      return ['-t', '--testNamePattern', '--testPathPattern', '--grep'].includes(head)
+    })
+    if (unsupported.length > 0) {
+      for (const arg of unsupported) {
+        const eq = arg.indexOf('=')
+        const head = eq > 0 ? arg.slice(0, eq) : arg
+        console.error(
+          `  error: ${head} selects detox/jest tests and does not apply to a maestro target`,
+        )
+      }
+      return 1
+    }
+  }
+  if (maestroTarget && statSync(targetPath).isDirectory()) {
+    const { collectFlowFiles, splitTagList } = await import('./maestro')
+    const tagFlag = (name: string): string[] | null => {
+      let values: string[] | null = null
+      for (let i = 0; i < forwarded.length; i++) {
+        const arg = forwarded[i]
+        const eq = arg.indexOf('=')
+        const head = eq > 0 ? arg.slice(0, eq) : arg
+        if (head !== name) continue
+        const inline = eq > 0 ? arg.slice(eq + 1) : null
+        const next = forwarded[i + 1]
+        const value = inline ?? (next !== undefined && !next.startsWith('-') ? next : '')
+        if (inline === null && next !== undefined && !next.startsWith('-')) i += 1
+        if (values === null) values = []
+        values.push(...splitTagList(value))
+      }
+      return values
+    }
+    const includeTags = tagFlag('--include-tags')
+    const excludeTags = tagFlag('--exclude-tags')
+    let flows: string[]
+    try {
+      flows = collectFlowFiles(targetPath, {
+        configPath: config ? resolve(process.cwd(), config) : undefined,
+        includeTags,
+        excludeTags,
+      })
+    } catch (err) {
+      console.error(`  error: ${err instanceof Error ? err.message : String(err)}`)
+      return 1
+    }
+    if (flows.length === 0) {
+      console.error(
+        includeTags !== null || excludeTags !== null
+          ? `  error: no flows in ${target} match the requested tags`
+          : `  error: no *.yaml or *.yml files found in ${target}`,
+      )
+      return 1
+    }
+    const baseFiles = collectTestFiles(targetPath, localBundlePath)
+    // tags have already selected the jobs. only explicit environment overrides
+    // remain executor inputs, with duplicates and their order preserved.
+    const envArgs: string[] = []
+    const executorArgs = cloudTestArgs ?? []
+    for (let i = 0; i < executorArgs.length; i++) {
+      const arg = executorArgs[i]
+      const eq = arg.indexOf('=')
+      const head = eq > 0 ? arg.slice(0, eq) : arg
+      const value = eq > 0 ? null : executorArgs[++i]
+      if (head !== '--env' && head !== '-e') continue
+      envArgs.push(arg)
+      if (value !== null) envArgs.push(value)
+    }
+    for (const flow of flows) {
+      const entryKey = relative(targetPath, flow).split(sep).join('/')
+      let generated: string
+      try {
+        generated = selectionConfig(entryKey)
+      } catch (err) {
+        console.error(`  error: ${err instanceof Error ? err.message : String(err)}`)
+        return 1
+      }
+      // the recorder selects the root workspace config. nested config.yaml
+      // files may be runFlow helpers and must keep their original bytes.
+      const testFiles = { ...baseFiles, 'config.yaml': generated }
+      jobs.push({ label: entryKey, testFiles, testArgs: envArgs.length ? envArgs : null })
+    }
+    console.log(
+      `  cloud test: ${jobs.length} flow${jobs.length === 1 ? '' : 's'}, one hosted job each`,
+    )
+  } else {
+    const testFiles = collectTestFiles(collectionPath, localBundlePath)
+    if (Object.keys(testFiles).length === 0) {
+      console.error(`  error: no test files found at ${target}`)
+      return 1
+    }
+    jobs.push({ label: null, testFiles, testArgs: cloudTestArgs })
+  }
 
-  // the tunnel stays open from submit until the job reaches a terminal
-  // state; tearing it down early strands the recorder mid-run.
+  // the tunnel stays open from the first submit until every job reaches a
+  // terminal state; tearing it down early strands the recorder mid-run.
   if (liveDevStack && liveSidecarPorts) {
     try {
       const published = await publishLiveDevStack({
         devPort: liveDevStack.port,
         sidecarPorts: liveSidecarPorts,
       })
-      tunnelTargetUrl = published.targetUrl
+      const appUrl = new URL(app)
+      const targetUrl = new URL(published.targetUrl)
+      targetUrl.pathname = appUrl.pathname
+      targetUrl.search = appUrl.search
+      tunnelTargetUrl = targetUrl.href
       tunnelHostHeader = published.hostHeader
       tunnelJobToken = published.jobToken
       tunnelSidecarPorts = published.sidecarPorts.join(',') || undefined
@@ -824,150 +986,229 @@ export async function runCloudTest(
     }
   }
 
-  const submitPayload: Record<string, unknown> = {
-    kind: 'test',
-    testFiles,
+  // a signal stops the run: it lets a submission already in flight finish, so
+  // an accepted job is never orphaned, cancels the job currently relying on
+  // this process's tunnel, and only then lets the tunnel close. the listener
+  // is installed once for the whole invocation and removed on the way out; a
+  // second signal waits for that cancellation instead of closing the tunnel
+  // while a delete is still pending.
+  const tunnelDependent = closeTunnel !== null
+  let interrupted = false
+  let wake: (() => void) | null = null
+  const onSignal = () => {
+    if (interrupted) {
+      console.error('  already stopping: waiting for the current job to cancel')
+      return
+    }
+    interrupted = true
+    console.error('\n  interrupted: stopping after the current job')
+    wake?.()
+  }
+  if (tunnelDependent) {
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
   }
-  if (bundleUrl) submitPayload.bundleUrl = bundleUrl
-  if (bundle) submitPayload.bundle = bundle
-  if (bundleShareId) submitPayload.bundleShareId = bundleShareId
-  if (tunnelTargetUrl) submitPayload.targetUrl = tunnelTargetUrl
-  if (tunnelHostHeader) submitPayload.hostHeader = tunnelHostHeader
-  if (tunnelJobToken) submitPayload.jobToken = tunnelJobToken
-  if (tunnelSidecarPorts) submitPayload.sidecarPorts = tunnelSidecarPorts
-  if (owner) submitPayload.owner = owner
-  if (repo) submitPayload.repo = repo
-  if (cloudTestArgs) submitPayload.testArgs = cloudTestArgs
 
-  try {
-    const endpoint = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs`
-    let response: Response
-    try {
-      response = await fetch(endpoint, {
-        method: 'POST',
-        headers: {
-          'content-type': 'application/json',
-          authorization: authHeaderValue(auth),
-        },
-        body: JSON.stringify(submitPayload),
-      })
-    } catch (err) {
-      console.error(
-        `  error: could not connect to ${endpoint}: ${err instanceof Error ? err.message : String(err)}`,
-      )
-      return 1
-    }
+  // a sleep the signal handler can cut short, so an interrupt is noticed while
+  // a job poll is waiting instead of after the whole interval.
+  const waitForPoll = (ms: number) =>
+    new Promise<void>((resolvePoll) => {
+      const timer = setTimeout(() => {
+        wake = null
+        resolvePoll()
+      }, ms)
+      wake = () => {
+        clearTimeout(timer)
+        wake = null
+        resolvePoll()
+      }
+    })
 
-    if (!response.ok) {
-      const body = await response.text()
-      let message = body
-      try {
-        const json = JSON.parse(body)
-        if (json.message) message = json.message
-      } catch {}
-      console.error(
-        `  error: cloud test submission failed (${response.status}): ${message}`,
-      )
-      return 1
-    }
+  const submitIdentity: Record<string, unknown> = {}
+  if (bundleUrl) submitIdentity.bundleUrl = bundleUrl
+  if (bundle) submitIdentity.bundle = bundle
+  if (bundleShareId) submitIdentity.bundleShareId = bundleShareId
+  if (tunnelTargetUrl) submitIdentity.targetUrl = tunnelTargetUrl
+  if (tunnelHostHeader) submitIdentity.hostHeader = tunnelHostHeader
+  if (tunnelJobToken) submitIdentity.jobToken = tunnelJobToken
+  if (tunnelSidecarPorts) submitIdentity.sidecarPorts = tunnelSidecarPorts
+  if (owner) submitIdentity.owner = owner
+  if (repo) submitIdentity.repo = repo
 
-    const { id } = (await response.json()) as { id: string }
-    console.log(`  cloud test job submitted: ${id}`)
-    // a job whose app this process serves over its tunnel cannot finish once
-    // the process exits, so an interrupt cancels it rather than leaving it to
-    // fail flow by flow while it bills.
-    if (closeTunnel) {
-      const cancelOnSignal = () => {
-        console.error(`\n  interrupted: cancelling ${id}`)
-        void cancelCloudTest(id, origin).finally(() => {
-          closeTunnel?.()
-          process.exit(130)
-        })
+  const summary: Array<{ label: string; passed: boolean }> = []
+  let worstExit = 0
+  try {
+    for (const [index, job] of jobs.entries()) {
+      const submitPayload: Record<string, unknown> = {
+        kind: 'test',
+        testFiles: job.testFiles,
+        ...submitIdentity,
       }
-      process.once('SIGINT', cancelOnSignal)
-      process.once('SIGTERM', cancelOnSignal)
-    }
+      if (job.testArgs) submitPayload.testArgs = job.testArgs
 
-    const pollUrl = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs?id=${encodeURIComponent(id)}`
-    const startedAt = Date.now()
-
-    while (Date.now() - startedAt < timeoutMs) {
-      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
-      let pollRes: Response
+      const endpoint = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs`
+      let response: Response
       try {
-        pollRes = await fetch(pollUrl, {
-          headers: { authorization: authHeaderValue(auth) },
+        response = await fetch(endpoint, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            authorization: authHeaderValue(auth),
+          },
+          body: JSON.stringify(submitPayload),
         })
       } catch (err) {
-        console.warn(
-          `  warn: error polling job: ${err instanceof Error ? err.message : String(err)}`,
+        // a transport failure is not a flow failure: stop submitting further
+        // jobs and report. jobs that already ran keep their collected results.
+        console.error(
+          `  error: could not connect to ${endpoint}: ${err instanceof Error ? err.message : String(err)}`,
         )
-        continue
+        if (interrupted) break
+        return 1
       }
-      if (!pollRes.ok) {
-        console.warn(`  warn: polling error: HTTP ${pollRes.status}`)
-        continue
+
+      if (!response.ok) {
+        const body = await response.text()
+        let message = body
+        try {
+          const json = JSON.parse(body)
+          if (json.message) message = json.message
+        } catch {}
+        console.error(
+          `  error: cloud test submission failed (${response.status}): ${message}`,
+        )
+        if (interrupted) break
+        return 1
       }
-      const job = (await pollRes.json()) as {
-        id: string
-        status: string
-        result?: {
-          previewId?: string | null
-          previewUrl?: string | null
-          runId?: string | null
-          flows?: Array<{
-            flow?: string | null
-            previewId?: string | null
-            previewUrl?: string | null
-            runId?: string | null
-          }> | null
-          exitCode?: number | null
-          failureReason?: string | null
-        } | null
+
+      const { id } = (await response.json()) as { id: string }
+      console.log(
+        jobs.length > 1
+          ? `  cloud test job ${index + 1}/${jobs.length} (${job.label}) submitted: ${id}`
+          : `  cloud test job submitted: ${id}`,
+      )
+      if (interrupted) {
+        // the signal arrived while the POST was in flight: the server accepted
+        // the job, so cancel it before the tunnel closes.
+        if (tunnelDependent) await cancelCloudTest(id, origin)
+        break
       }
 
-      if (
-        job.status === 'done' ||
-        job.status === 'failed' ||
-        job.status === 'expired' ||
-        job.status === 'cancelled'
-      ) {
-        const result = job.result
-        // a job the recorder failed after a passing suite (missing recording or
-        // registration) is still a failed run.
-        const exitCode =
-          job.status === 'done' ? (result?.exitCode ?? 0) : result?.exitCode || 1
-        console.log(`  status:    ${job.status}`)
-        console.log(`  exit code: ${exitCode}`)
-        if (result?.previewUrl) {
-          console.log(`  preview:   ${result.previewUrl}`)
-        } else if (result?.previewId) {
-          console.log(
-            `  preview:   ${origin.replace(/\/$/, '')}/preview/${result.previewId}`,
+      const pollUrl = `${origin.replace(/\/$/, '')}/api/sootsim/runner/jobs?id=${encodeURIComponent(id)}`
+      const startedAt = Date.now()
+      let exitCode: number | null = null
+
+      // every flow keeps the job's own budget; a wait that expires cancels
+      // the job before the tunnel closes, and later flows are not submitted.
+      while (!interrupted && Date.now() - startedAt < timeoutMs) {
+        await waitForPoll(pollIntervalMs)
+        if (interrupted) break
+        let pollRes: Response
+        try {
+          pollRes = await fetch(pollUrl, {
+            headers: { authorization: authHeaderValue(auth) },
+          })
+        } catch (err) {
+          console.warn(
+            `  warn: error polling job: ${err instanceof Error ? err.message : String(err)}`,
           )
+          continue
         }
-        if (result?.runId) {
-          console.log(`  run:       ${result.runId}`)
+        if (interrupted) break
+        if (!pollRes.ok) {
+          console.warn(`  warn: polling error: HTTP ${pollRes.status}`)
+          continue
         }
-        if (result?.flows && result.flows.length > 1) {
-          result.flows.forEach((flow, index) => {
+        const jobState = (await pollRes.json()) as {
+          id: string
+          status: string
+          result?: {
+            previewId?: string | null
+            previewUrl?: string | null
+            runId?: string | null
+            flows?: Array<{
+              flow?: string | null
+              previewId?: string | null
+              previewUrl?: string | null
+              runId?: string | null
+            }> | null
+            exitCode?: number | null
+            failureReason?: string | null
+          } | null
+        }
+
+        if (
+          jobState.status === 'done' ||
+          jobState.status === 'failed' ||
+          jobState.status === 'expired' ||
+          jobState.status === 'cancelled'
+        ) {
+          const result = jobState.result
+          // a job the recorder failed after a passing suite (missing recording or
+          // registration) is still a failed run.
+          exitCode =
+            jobState.status === 'done' ? (result?.exitCode ?? 0) : result?.exitCode || 1
+          console.log(`  status:    ${jobState.status}`)
+          console.log(`  exit code: ${exitCode}`)
+          if (result?.previewUrl) {
+            console.log(`  preview:   ${result.previewUrl}`)
+          } else if (result?.previewId) {
             console.log(
-              `  flow ${index + 1}:    ${flow.flow ?? '(unknown flow)'} preview=${flow.previewUrl ?? flow.previewId ?? 'none'} run=${flow.runId ?? 'none'}`,
+              `  preview:   ${origin.replace(/\/$/, '')}/preview/${result.previewId}`,
             )
-          })
+          }
+          if (result?.runId) {
+            console.log(`  run:       ${result.runId}`)
+          }
+          if (result?.flows && (result.flows.length > 1 || jobs.length > 1)) {
+            result.flows.forEach((flow, flowIndex) => {
+              console.log(
+                `  flow ${flowIndex + 1}:    ${flow.flow ?? job.label ?? '(unknown flow)'} preview=${flow.previewUrl ?? flow.previewId ?? 'none'} run=${flow.runId ?? 'none'}`,
+              )
+            })
+          }
+          if (result?.failureReason) {
+            console.error(`  failure:   ${result.failureReason}`)
+          }
+          break
         }
-        if (result?.failureReason) {
-          console.error(`  failure:   ${result.failureReason}`)
-        }
-        return exitCode
       }
-    }
 
-    console.error(
-      `  error: cloud test timed out after ${timeoutMs < 1000 ? `${timeoutMs}ms` : `${timeoutMs / 1000}s`}`,
-    )
-    return 1
+      if (exitCode === null) {
+        // the wait ended without a terminal state: the budget ran out or a
+        // signal asked to stop. a tunnel-dependent job is cancelled before
+        // the tunnel closes instead of failing flow by flow while it bills.
+        if (tunnelDependent) await cancelCloudTest(id, origin)
+        if (interrupted) break
+        console.error(
+          `  error: cloud test timed out after ${timeoutMs < 1000 ? `${timeoutMs}ms` : `${timeoutMs / 1000}s`}`,
+        )
+        return 1
+      }
+
+      summary.push({ label: job.label ?? id, passed: exitCode === 0 })
+      if (exitCode !== 0 && worstExit === 0) worstExit = exitCode
+      if (interrupted) break
+    }
+    if (interrupted) return 130
+    return worstExit
   } finally {
+    if (tunnelDependent) {
+      process.off('SIGINT', onSignal)
+      process.off('SIGTERM', onSignal)
+    }
+    if (jobs.length > 1 && summary.length > 0) {
+      console.log('\n  cloud test summary:')
+      for (const entry of summary) {
+        console.log(`    ${entry.passed ? 'pass' : 'fail'}  ${entry.label}`)
+      }
+      const passed = summary.filter((entry) => entry.passed).length
+      const stopped =
+        summary.length < jobs.length
+          ? ` (stopped after ${summary.length} of ${jobs.length})`
+          : ''
+      console.log(`    ${passed}/${summary.length} flows passed${stopped}`)
+    }
     closeTunnel?.()
   }
 }

package/cli/drivers/playwright-core-pin.ts

@@ -0,0 +1,10 @@
+// the playwright-core this CLI provisions into its own data dir when neither
+// the app nor the CLI's install tree has a playwright package. the standalone
+// binary has no node_modules, so this is how it gets one. it is the exact
+// package and tarball the npm install depends on: build-cli-binary.ts fails
+// unless both fields match package.json and bun.lock.
+export const PINNED_PLAYWRIGHT_CORE = {
+  version: '1.61.0',
+  integrity:
+    'sha512-caX7TrY3Ml6egyDX0WUcTHDxodl/b51y5wJOdCEA36QviK/s2g081hvmGs8eaE3DWb6NYZQ6BjO/QkNRPenoPA==',
+}

package/cli/drivers/playwright-provisioning.ts

@@ -2,9 +2,12 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
+import { installVerifiedTarball } from '@contrast/runtime-delivery'
+import { playwrightCoreDir } from '../../src/home-paths'
 import { isRecord } from '../../src/is-record'
 import { RNX_INTERNAL_CHILDREN, RNX_INTERNAL_COMMAND } from '../internal-child'
 import { rnxSelfInvocation } from '../self-invocation'
+import { PINNED_PLAYWRIGHT_CORE } from './playwright-core-pin'
 
 export interface ResolvedPlaywright {
   // package name that resolved (for human-facing messaging)
@@ -30,10 +33,12 @@ export type PlaywrightBrowserProvisioningResult =
 
 export function resolvePlaywright(): ResolvedPlaywright | null {
   // resolve from several roots, not just cwd. a user can invoke a global CLI
-  // from an arbitrary directory while Playwright is installed beside the CLI.
+  // from an arbitrary directory while Playwright is installed beside the CLI,
+  // and the last root is the pinned package this CLI provisions for itself.
   const roots = [`${process.cwd()}/`]
   const self = rnxSelfInvocation()
   roots.push(self.prefixArgs[0] ?? self.executable)
+  roots.push(`${playwrightCoreDir(PINNED_PLAYWRIGHT_CORE.version)}/`)
   for (const root of roots) {
     try {
       const requireFromRoot = createRequire(root)
@@ -69,6 +74,36 @@ export function resolvePlaywright(): ResolvedPlaywright | null {
   return null
 }
 
+/** the playwright package to drive: whichever one resolves, else the pinned
+ *  playwright-core, downloaded from the npm registry and refused unless its
+ *  tarball matches the pinned integrity. */
+export async function provisionPlaywright(): Promise<ResolvedPlaywright> {
+  const existing = resolvePlaywright()
+  if (existing) return existing
+  const { version, integrity } = PINNED_PLAYWRIGHT_CORE
+  const [algorithm, digest] = integrity.split('-', 2)
+  if (algorithm !== 'sha512' || !digest) {
+    throw new Error(`pinned playwright-core integrity is not sha512: ${integrity}`)
+  }
+  process.stderr.write(`peach: installing playwright-core ${version}…\n`)
+  await installVerifiedTarball({
+    url: `https://registry.npmjs.org/playwright-core/-/playwright-core-${version}.tgz`,
+    digest: { algorithm, encoding: 'base64', value: digest },
+    destDir: join(playwrightCoreDir(version), 'node_modules', 'playwright-core'),
+    installedMarker: 'package.json',
+    // npm tarballs hold the package under a leading `package/`
+    stripComponents: 1,
+    label: `playwright-core ${version}`,
+  })
+  const installed = resolvePlaywright()
+  if (!installed) {
+    throw new Error(
+      `playwright-core ${version} installed to ${playwrightCoreDir(version)} but does not resolve`,
+    )
+  }
+  return installed
+}
+
 type BrowserProbeResult =
   | { ok: true; executablePath: string; exists: boolean }
   | { ok: false; message: string }