rnxsim 0.1.549 → 0.1.551

package/cli/bridge-flow-runner.ts

@@ -2027,7 +2027,33 @@ export class SootSimBridgeFlowRunner {
       // begin its pixels only after launch has mounted and settled, leaving the
       // loading prelude outside the playable video while its trace stays visible.
       await this.waitForVisualSettle()
+      const videoAlreadyStarted = this.recordingStartedAtMs != null
       await this.ensureRecordingStarted()
+      if (!videoAlreadyStarted && this.recordingStartedAtMs != null) {
+        // the preview event recorder has been running since before launch,
+        // so its clock includes the boot prelude the video just skipped.
+        // rebase it to the video's first frame — without this every event
+        // timestamp overshoots the playable video and preview playback can
+        // never align (play stuck disabled). no-op unless the preview
+        // event recorder is running.
+        await this.rebaseEventRecorderToVideoStart(this.recordingStartedAtMs)
+      }
+    }
+  }
+
+  private async rebaseEventRecorderToVideoStart(videoStartedAtMs: number) {
+    try {
+      await this.evaluate(
+        `(() => {
+          const recorder = window.SootSim?.bridges?.eventRecorder ?? window.__sootsimEventRecorder
+          if (!recorder?.isRecording?.()) return 'not-recording'
+          return recorder.markVisibleStart?.(${JSON.stringify(videoStartedAtMs)}) ?? 'no-mark'
+        })()`,
+      )
+    } catch (err) {
+      console.warn(
+        `  warn: event-recorder rebase to video start failed: ${err instanceof Error ? err.message : err}`,
+      )
     }
   }
 

package/cli/commands/maestro.ts

@@ -10,7 +10,16 @@ import * as fs from 'fs'
 import * as path from 'path'
 import yaml from 'yaml'
 import { resolveCliAuth } from '../auth'
-import { parseFlowFile } from '../flow-file'
+import { parseFlowFile, type FlowFrontmatter } from '../flow-file'
+import {
+  buildFlowCommandsJson,
+  buildFlowLogLines,
+  buildJUnitXml,
+  buildSessionLog,
+  failureFromTraceSteps,
+  type JUnitCaseInput,
+  type SessionLogFlow,
+} from '../maestro-report'
 import { registerRun, shouldRegisterRun, stepSummaryFromTrace } from '../run-registry'
 import { RnxExit } from '../run-rnx'
 import {
@@ -50,7 +59,19 @@ options:
   --dry-run, --no-run    load flow into runner idle without auto-running
   --env KEY=VALUE        set env vars for \${KEY} interpolation (repeatable)
   --continuous           accepted for maestro cli compat; rnx runs the flow once
-  --format <fmt>         accepted for maestro cli compat (not used)
+  --include-tags <a,b>   run only flows carrying one of these tags (comma-
+                         separated; CLI wins over config.yaml includeTags)
+  --exclude-tags <a,b>   skip flows carrying any of these tags
+  --config <path>        read the workspace config (flows/tags) from this file
+                         instead of <dir>/config.yaml
+  --format junit         write a junit xml report (default ./report.xml)
+  --output <file>        junit report path (needs --format junit)
+  --test-output-dir <dir>
+                         per-flow screenshots, commands.json, and logs/maestro.log
+                         (config key testOutputDir:; CLI wins over config)
+  --debug-output <dir>   write a session maestro.log there
+  --platform ios         accepted; any other platform is refused (rnx is iOS-only)
+  --no-ansi              accepted; rnx output is already plain text
   --device <model>       override the flow frontmatter device for this run
   --new                  force a fresh browser window for this run
   --headed               force a fresh, VISIBLE window (implies --new,
@@ -95,8 +116,19 @@ supported verbs:
   (env vars as globals, output.*, maestro.*, \${EXPR || 'default'}).
 
 workspace mode (directory runs):
-  config.yaml / config.yml discovery, flows: inclusion globs,
-  includeTags / excludeTags against flow frontmatter tags.
+  config.yaml / config.yml discovery, flows: inclusion globs (with !
+  negation; at least one positive pattern), includeTags / excludeTags
+  against flow frontmatter tags.
+
+cli flags (maestro test parity):
+  --include-tags / --exclude-tags (comma-separated, OR within a flag;
+  CLI wins over config.yaml), --config <path>, --format junit with
+  --output (default report.xml; flow name:/properties: shape the
+  testcase), --test-output-dir (config key testOutputDir:, CLI wins),
+  --debug-output, --platform ios (others refused), --no-ansi (rnx
+  output is already plain), -d for --device, -e for --env.
+  --continuous warns and runs once; --format html warns and runs
+  without a report.
 
 launch behavior:
   launchApp.arguments: a JSON object available before guest app entry through
@@ -150,19 +182,109 @@ function applyEnvFlags(args: string[]): string[] {
   return out
 }
 
-// maestro-cli flags with no rnx equivalent, accepted so an existing script can
-// swap `maestro` for `rnx maestro` unedited. each one says out loud that it is
-// being ignored: an option that is quietly dropped is how a run reports success
-// while doing something other than what was asked. `--origin` is consumed here
-// because only this command reads it; everything else this function leaves
-// alone rides on to the flow runner, which rejects what it does not know.
-function stripMaestroCompatFlags(args: string[]): string[] {
-  const out: string[] = []
+// maestro-cli flags this command consumes itself, accepted so an existing
+// script can swap `maestro test` for `rnx maestro test` unedited. each one
+// either takes effect below or says out loud that it does not: an option
+// that is quietly dropped is how a run reports success while doing something
+// other than what was asked. `--origin` is consumed here because only this
+// command reads it; everything this function leaves alone rides on to the
+// flow runner, which rejects what it does not know.
+//
+// both `--flag value` and `--flag=value` spellings work: maestro's own docs
+// use the `=` form for tags and output dirs, so rejecting it would break the
+// exact command lines users paste from there.
+export interface MaestroCompatOptions {
+  // null = flag absent. CLI lists take precedence over config.yaml (maestro
+  // documents CLI-always-wins), so absent must stay distinguishable from [].
+  includeTags: string[] | null
+  excludeTags: string[] | null
+  configPath: string | null
+  format: string | null
+  output: string | null
+  testOutputDir: string | null
+  debugOutput: string | null
+  platform: string | null
+}
+
+const MAESTRO_COMPAT_VALUE_FLAGS = new Set([
+  '--include-tags',
+  '--exclude-tags',
+  '--config',
+  '--format',
+  '--output',
+  '--test-output-dir',
+  '--debug-output',
+  '--platform',
+])
+
+function splitTagList(value: string): string[] {
+  return value
+    .split(',')
+    .map((tag) => tag.trim())
+    .filter((tag) => tag.length > 0)
+}
+
+export function extractMaestroCompatFlags(args: string[]): {
+  rest: string[]
+  compat: MaestroCompatOptions
+} {
+  const compat: MaestroCompatOptions = {
+    includeTags: null,
+    excludeTags: null,
+    configPath: null,
+    format: null,
+    output: null,
+    testOutputDir: null,
+    debugOutput: null,
+    platform: null,
+  }
+  const rest: string[] = []
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
-    if (a === '--format' || a === '--output') {
-      console.warn(`  warn: ${a} is accepted for maestro cli compatibility and ignored`)
-      i += 1
+    const eq = a.indexOf('=')
+    const head = eq > 0 ? a.slice(0, eq) : a
+    if (MAESTRO_COMPAT_VALUE_FLAGS.has(head)) {
+      const inline = eq > 0 ? a.slice(eq + 1) : null
+      const next = args[i + 1]
+      const value =
+        inline !== null && inline.length > 0
+          ? inline
+          : next !== undefined && !next.startsWith('-')
+            ? next
+            : null
+      if (inline === null || inline.length === 0) i += 1
+      if (value === null || value.length === 0) {
+        throw new Error(`${head} expects a value`)
+      }
+      switch (head) {
+        case '--include-tags':
+          compat.includeTags = [...(compat.includeTags ?? []), ...splitTagList(value)]
+          break
+        case '--exclude-tags':
+          compat.excludeTags = [...(compat.excludeTags ?? []), ...splitTagList(value)]
+          break
+        case '--config':
+          compat.configPath = value
+          break
+        case '--format':
+          compat.format = value
+          break
+        case '--output':
+          compat.output = value
+          break
+        case '--test-output-dir':
+          compat.testOutputDir = value
+          break
+        case '--debug-output':
+          compat.debugOutput = value
+          break
+        case '--platform':
+          if (value.toLowerCase() !== 'ios') {
+            throw new Error(`rnx emulates iOS only; --platform ${value} is not supported`)
+          }
+          compat.platform = value
+          break
+      }
       continue
     }
     if (a === '--origin') {
@@ -174,16 +296,26 @@ function stripMaestroCompatFlags(args: string[]): string[] {
     if (a === '-d') {
       // maestro's short form for --device. rnx's device flag names a device
       // model, and the flow runner reads it under the long spelling only.
-      out.push('--device')
+      rest.push('--device')
+      continue
+    }
+    if (a === '--no-ansi') {
+      // trivially satisfied: rnx prints no ANSI escapes anywhere on this path.
       continue
     }
     if (a === '--continuous') {
       console.warn('  warn: --continuous is not implemented in rnx — running once')
       continue
     }
-    out.push(a)
+    rest.push(a)
   }
-  return out
+  if (
+    compat.format !== null &&
+    !['junit', 'html', 'html-detailed'].includes(compat.format)
+  ) {
+    throw new Error(`unsupported --format: ${compat.format} (rnx writes junit reports)`)
+  }
+  return { rest, compat }
 }
 
 function findDefaultMaestroTarget(cwd: string): string | null {
@@ -198,36 +330,88 @@ interface MaestroWorkspaceConfig {
   flows?: string[]
   includeTags?: string[]
   excludeTags?: string[]
+  testOutputDir?: string
+}
+
+export interface CollectFlowFilesOptions {
+  // explicit `--config <path>`; globs still resolve under the target dir.
+  configPath?: string
+  // CLI tag lists; null/undefined falls back to the workspace config (maestro
+  // documents CLI-always-wins, never a union).
+  includeTags?: string[] | null
+  excludeTags?: string[] | null
+}
+
+// read the workspace config for a directory target: an explicit --config
+// path, else config.yaml/config.yml beside the flows, else empty policy.
+export function loadMaestroWorkspaceConfig(
+  dir: string,
+  configPath?: string,
+): { path: string | null; config: MaestroWorkspaceConfig } {
+  const found =
+    configPath ??
+    ['config.yaml', 'config.yml']
+      .map((name) => path.join(dir, name))
+      .find((p) => fs.existsSync(p))
+  if (!found) return { path: null, config: {} }
+  if (!fs.existsSync(found)) {
+    throw new Error(`maestro config not found: ${configPath}`)
+  }
+  // yaml.parse returns any; shape-check the fields we use below instead
+  // of trusting the file
+  const parsed: unknown = yaml.parse(fs.readFileSync(found, 'utf8'))
+  if (!parsed || typeof parsed !== 'object') return { path: found, config: {} }
+  const raw = parsed as Record<string, unknown>
+  const config: MaestroWorkspaceConfig = {}
+  if (Array.isArray(raw.flows)) {
+    config.flows = raw.flows.filter((g): g is string => typeof g === 'string')
+  }
+  if (Array.isArray(raw.includeTags)) {
+    config.includeTags = raw.includeTags.filter((t): t is string => typeof t === 'string')
+  }
+  if (Array.isArray(raw.excludeTags)) {
+    config.excludeTags = raw.excludeTags.filter((t): t is string => typeof t === 'string')
+  }
+  if (typeof raw.testOutputDir === 'string' && raw.testOutputDir.length > 0) {
+    config.testOutputDir = raw.testOutputDir
+  }
+  return { path: found, config }
 }
 
 // workspace planning for directory targets — mirrors maestro's
 // WorkspaceExecutionPlanner: discover config.yaml/config.yml in the
 // directory, walk it recursively for *.yaml/*.yml flow files (config files
 // excluded), keep the ones matching the config's `flows:` globs (default
-// `*` = top level only), then filter by includeTags/excludeTags against
-// each flow's frontmatter `tags:`.
-export function collectFlowFiles(target: string): string[] {
+// `*` = top level only; `!`-prefixed globs subtract from the positive
+// matches), then filter by includeTags/excludeTags against each flow's
+// frontmatter `tags:` (OR within a flag, include-then-exclude between them).
+//
+// an explicit file target always runs: maestro runs a named flow even when
+// its tags would exclude it from a directory run.
+export function collectFlowFiles(
+  target: string,
+  opts: CollectFlowFilesOptions = {},
+): string[] {
   const stat = fs.statSync(target)
   if (stat.isFile()) return [target]
   if (!stat.isDirectory()) {
     throw new Error(`not a file or directory: ${target}`)
   }
 
-  let config: MaestroWorkspaceConfig = {}
-  const configPath = ['config.yaml', 'config.yml']
-    .map((name) => path.join(target, name))
-    .find((p) => fs.existsSync(p))
-  if (configPath) {
-    // yaml.parse returns any; shape-check the fields we use below instead
-    // of trusting the file
-    const parsed = yaml.parse(fs.readFileSync(configPath, 'utf8'))
-    if (parsed && typeof parsed === 'object') {
-      config = parsed
-    }
-  }
+  const { path: configPath, config } = loadMaestroWorkspaceConfig(target, opts.configPath)
 
   const globs =
     Array.isArray(config.flows) && config.flows.length > 0 ? config.flows : ['*']
+  const positive = globs.filter((glob) => !glob.startsWith('!'))
+  const negative = globs
+    .filter((glob) => glob.startsWith('!'))
+    .map((glob) => glob.slice(1))
+    .filter((glob) => glob.length > 0)
+  if (positive.length === 0) {
+    throw new Error(
+      `flows: needs at least one positive pattern in ${configPath ?? target} (got only exclusions)`,
+    )
+  }
   const isFlowFile = (rel: string) => {
     const base = path.basename(rel)
     if (base.startsWith('.')) return false
@@ -236,17 +420,22 @@ export function collectFlowFiles(target: string): string[] {
     return true
   }
   const matched = new Set<string>()
-  for (const glob of globs) {
+  for (const glob of positive) {
     for (const rel of fs.globSync(glob, { cwd: target })) {
       if (!isFlowFile(rel)) continue
       const abs = path.join(target, rel)
       if (fs.existsSync(abs) && fs.statSync(abs).isFile()) matched.add(abs)
     }
   }
+  for (const glob of negative) {
+    for (const rel of fs.globSync(glob, { cwd: target })) {
+      matched.delete(path.join(target, rel))
+    }
+  }
   let files = [...matched].sort()
 
-  const includeTags = Array.isArray(config.includeTags) ? config.includeTags : []
-  const excludeTags = Array.isArray(config.excludeTags) ? config.excludeTags : []
+  const includeTags = opts.includeTags ?? config.includeTags ?? []
+  const excludeTags = opts.excludeTags ?? config.excludeTags ?? []
   if (includeTags.length > 0 || excludeTags.length > 0) {
     files = files.filter((file) => {
       const { frontmatter } = parseFlowFile(fs.readFileSync(file, 'utf8'))
@@ -261,6 +450,23 @@ export function collectFlowFiles(target: string): string[] {
   return files
 }
 
+function flowFileStem(file: string): string {
+  return path.basename(file).replace(/\.(ya?ml)$/i, '')
+}
+
+// a per-flow artifact dir under the test-output root. never reuses a dir,
+// so a re-run cannot overwrite the previous run's evidence.
+function uniqueFlowDir(root: string, file: string): string {
+  const slug = flowFileStem(file).replace(/[^A-Za-z0-9._-]+/g, '_') || 'flow'
+  let dir = path.join(root, slug)
+  let n = 2
+  while (fs.existsSync(dir)) {
+    dir = path.join(root, `${slug}-${n}`)
+    n += 1
+  }
+  return dir
+}
+
 async function runInit(cwd: string): Promise<number> {
   const dir = path.join(cwd, '.maestro')
   fs.mkdirSync(dir, { recursive: true })
@@ -345,11 +551,27 @@ export async function runMaestro(
     return runMaestroAuthoring(remaining)
   }
   // `--origin` names the Contrast instance that hosts the run row. this command
-  // is its only reader, so read it before stripMaestroCompatFlags consumes it.
+  // is its only reader, so read it before the compat extractor consumes it.
   const originFlagIndex = remaining.indexOf('--origin')
   const originFlagValue =
     originFlagIndex >= 0 ? remaining[originFlagIndex + 1] : undefined
-  remaining = stripMaestroCompatFlags(remaining)
+  let compat: MaestroCompatOptions
+  try {
+    const extracted = extractMaestroCompatFlags(remaining)
+    remaining = extracted.rest
+    compat = extracted.compat
+  } catch (err) {
+    console.error(`  error: ${(err as Error).message}`)
+    return 1
+  }
+  if (compat.format === 'html' || compat.format === 'html-detailed') {
+    console.warn(
+      `  warn: --format ${compat.format} reports are not implemented in rnx — running without writing a report`,
+    )
+  }
+  if (compat.output && compat.format !== 'junit') {
+    console.warn('  warn: --output is ignored without --format junit')
+  }
 
   // resolve the target flow file or directory.
   let target: string | null = null
@@ -368,6 +590,11 @@ export async function runMaestro(
     if (positionalIndex >= 0) {
       target = path.resolve(cwd, rest[positionalIndex])
       forwardArgs = rest.filter((_, i) => i !== positionalIndex)
+    } else if (compat.configPath) {
+      // no positional with an explicit workspace config: run the directory
+      // the config lives in, like `rnx test --config` does.
+      target = path.resolve(cwd, path.dirname(compat.configPath))
+      forwardArgs = rest
     } else {
       target = findDefaultMaestroTarget(cwd)
       forwardArgs = rest
@@ -411,18 +638,42 @@ export async function runMaestro(
   }
 
   let files: string[]
+  let workspaceConfig: MaestroWorkspaceConfig = {}
+  let workspaceConfigPath: string | null = null
   try {
-    files = collectFlowFiles(target)
+    if (fs.statSync(target).isDirectory()) {
+      const loaded = loadMaestroWorkspaceConfig(target, compat.configPath ?? undefined)
+      workspaceConfig = loaded.config
+      workspaceConfigPath = loaded.path
+    }
+    files = collectFlowFiles(target, {
+      configPath: compat.configPath ?? undefined,
+      includeTags: compat.includeTags,
+      excludeTags: compat.excludeTags,
+    })
   } catch (err) {
     console.error(`  error: ${(err as Error).message}`)
     return 1
   }
 
   if (files.length === 0) {
+    if (compat.includeTags !== null || compat.excludeTags !== null) {
+      console.error(`  error: no flows in ${target} match the requested tags`)
+      return 1
+    }
     console.error(`  error: no *.yaml or *.yml files found in ${target}`)
     return 1
   }
 
+  // maestro's priority rule: CLI flag, then config.yaml, then the default
+  // (which for rnx is no test-output routing at all). a config-relative dir
+  // resolves against the config file, a CLI dir against the invocation cwd.
+  const testOutputRoot = compat.testOutputDir
+    ? path.resolve(cwd, compat.testOutputDir)
+    : workspaceConfig.testOutputDir && workspaceConfigPath
+      ? path.resolve(path.dirname(workspaceConfigPath), workspaceConfig.testOutputDir)
+      : null
+
   console.log(`
   rnx maestro — ${files.length} flow${files.length === 1 ? '' : 's'}
   root: ${path.relative(cwd, target) || '.'}
@@ -445,11 +696,36 @@ export async function runMaestro(
       flagValue('--preview-origin') ?? originFlagValue,
     ))
 
+  const sessionStartedAt = new Date().toISOString()
   let worstExit = 0
-  const results: Array<{ file: string; exit: number }> = []
+  const results: Array<{
+    file: string
+    exit: number
+    durationMs: number
+    steps: ReturnType<typeof getLastFlowTraceSteps>
+    frontmatter: FlowFrontmatter
+  }> = []
   for (const file of files) {
     console.log(`\n  ▶ ${path.relative(cwd, file)}`)
     const playbackArgs = [file, ...forwardArgs]
+    let flowTestDir: string | null = null
+    if (testOutputRoot) {
+      flowTestDir = uniqueFlowDir(testOutputRoot, file)
+      try {
+        fs.mkdirSync(path.join(flowTestDir, 'screenshots'), { recursive: true })
+        fs.mkdirSync(path.join(flowTestDir, 'logs'), { recursive: true })
+      } catch (err) {
+        console.error(
+          `  error: could not create test output dir: ${(err as Error).message}`,
+        )
+        results.push({ file, exit: 1, durationMs: 0, steps: [], frontmatter: {} })
+        if (worstExit === 0) worstExit = 1
+        continue
+      }
+      // an explicit --screenshots wins over this routing: flow.ts reads the
+      // FIRST occurrence, and the user's flag sits earlier in playbackArgs.
+      playbackArgs.push('--screenshots', path.join(flowTestDir, 'screenshots'))
+    }
     // `--port` is the BRIDGE port everywhere else in the CLI, so forward it as
     // one. sending it on as `--url` made it an app target instead, which left
     // the playback bridge on whichever world resolveBridgeWorld picks by
@@ -476,9 +752,42 @@ export async function runMaestro(
         exit = 1
       }
     }
-    results.push({ file, exit })
+    const traceSteps = getLastFlowTraceSteps()
+    const durationMs = Date.now() - startedAt
+    let frontmatter: FlowFrontmatter = {}
+    try {
+      frontmatter = parseFlowFile(fs.readFileSync(file, 'utf8')).frontmatter
+    } catch {
+      frontmatter = {}
+    }
+    const result = { file, exit, durationMs, steps: traceSteps, frontmatter }
+    results.push(result)
     if (exit !== 0 && worstExit === 0) worstExit = exit
 
+    if (flowTestDir) {
+      try {
+        fs.writeFileSync(
+          path.join(flowTestDir, 'commands.json'),
+          buildFlowCommandsJson(traceSteps),
+        )
+        fs.writeFileSync(
+          path.join(flowTestDir, 'logs', 'maestro.log'),
+          `${buildFlowLogLines({
+            file: path.relative(cwd, file) || file,
+            passed: exit === 0,
+            durationMs,
+            steps: traceSteps,
+          }).join('\n')}\n`,
+        )
+      } catch (err) {
+        console.error(
+          `  error: could not write test artifacts: ${(err as Error).message}`,
+        )
+        if (exit === 0) exit = 1
+        if (worstExit === 0) worstExit = 1
+      }
+    }
+
     const upload = getLastFlowPreviewUploadResult()
     if (upload?.shareId || upload?.previewUrl) {
       try {
@@ -497,7 +806,6 @@ export async function runMaestro(
     }
 
     if (shouldRegisterRun({ uploadedShare: Boolean(upload), auth })) {
-      const traceSteps = getLastFlowTraceSteps()
       const failedStep = traceSteps.find((step) => step.status === 'failure')
       const run = await registerRun({
         origin: await registerOrigin(),
@@ -530,6 +838,9 @@ export async function runMaestro(
         if (worstExit === 0) worstExit = 1
       }
     }
+    // artifact, upload, and registration failures above flip the local exit
+    // after the result was pushed; the report below must see the final one.
+    result.exit = exit
   }
 
   if (files.length > 1) {
@@ -542,5 +853,105 @@ export async function runMaestro(
     console.log(`  ${passed}/${results.length} passed`)
   }
 
+  // one device per invocation, like maestro: the explicit override, else the
+  // sim default. reports print it; playback already resolved it per flow.
+  const deviceLabel = flagValue('--device')?.trim() || 'iPhone 17 Pro'
+  if (compat.format === 'junit') {
+    const junitPath = path.resolve(cwd, compat.output ?? 'report.xml')
+    try {
+      fs.mkdirSync(path.dirname(junitPath), { recursive: true })
+      fs.writeFileSync(
+        junitPath,
+        buildJUnitXml({
+          device: deviceLabel,
+          cases: results.map((r) => junitCaseForResult(cwd, r)),
+        }),
+      )
+      console.log(`  junit: ${path.relative(cwd, junitPath) || junitPath}`)
+    } catch (err) {
+      console.error(`  error: could not write junit report: ${(err as Error).message}`)
+      if (worstExit === 0) worstExit = 1
+    }
+  }
+  if (compat.debugOutput) {
+    const logPath = path.resolve(cwd, compat.debugOutput, 'maestro.log')
+    try {
+      fs.mkdirSync(path.dirname(logPath), { recursive: true })
+      const sessionFlows: SessionLogFlow[] = results.map((r) => ({
+        file: path.relative(cwd, r.file) || r.file,
+        passed: r.exit === 0,
+        durationMs: r.durationMs,
+        steps: r.steps,
+      }))
+      fs.writeFileSync(
+        logPath,
+        buildSessionLog({
+          startedAtIso: sessionStartedAt,
+          root: path.relative(cwd, target) || '.',
+          device: deviceLabel,
+          flows: sessionFlows,
+        }),
+      )
+      console.log(`  debug log: ${path.relative(cwd, logPath) || logPath}`)
+    } catch (err) {
+      console.error(`  error: could not write debug log: ${(err as Error).message}`)
+      if (worstExit === 0) worstExit = 1
+    }
+  }
+
   return worstExit
 }
+
+// a junit testcase from one flow result. yaml frontmatter is untrusted, so
+// every field is shape-checked back to the documented scalar shapes.
+function junitCaseForResult(
+  cwd: string,
+  result: {
+    file: string
+    exit: number
+    durationMs: number
+    steps: ReturnType<typeof getLastFlowTraceSteps>
+    frontmatter: FlowFrontmatter
+  },
+): JUnitCaseInput {
+  const raw = result.frontmatter
+  const name =
+    typeof raw.name === 'string' && raw.name.trim().length > 0
+      ? raw.name.trim()
+      : flowFileStem(result.file)
+  const custom: Record<string, string> = {}
+  let junitId: string | null = null
+  let junitClassname: string | null = null
+  const props: unknown = raw.properties
+  if (props && typeof props === 'object') {
+    for (const [key, value] of Object.entries(props)) {
+      if (
+        typeof value !== 'string' &&
+        typeof value !== 'number' &&
+        typeof value !== 'boolean'
+      ) {
+        continue
+      }
+      const text = String(value)
+      if (key === 'junitId') junitId = text
+      else if (key === 'junitClassname') junitClassname = text
+      else custom[key] = text
+    }
+  }
+  const tags = Array.isArray(raw.tags)
+    ? raw.tags.filter((tag): tag is string => typeof tag === 'string')
+    : []
+  return {
+    file: path.relative(cwd, result.file) || result.file,
+    name,
+    id: junitId ?? name,
+    classname: junitClassname ?? name,
+    properties: custom,
+    tags,
+    timeSeconds: result.durationMs / 1000,
+    failure:
+      result.exit === 0
+        ? null
+        : failureFromTraceSteps(result.steps, 'flow playback failed'),
+  }
+}