peachsim 0.1.527 → 0.1.571

package/cli/commands/maestro.ts

@@ -10,7 +10,17 @@ import * as fs from 'fs'
 import * as path from 'path'
 import yaml from 'yaml'
 import { resolveCliAuth } from '../auth'
-import { parseFlowFile } from '../flow-file'
+import { cloudTestResultFileNames } from '../cloud-test-result-files'
+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 {
@@ -38,6 +48,7 @@ rnx maestro — author and run Maestro YAML flows against rnx
 usage:
   rnx maestro                         # discover .maestro/ or maestro/ in cwd, run all
   rnx maestro test <flow-or-dir>      # mirrors "maestro test"
+  rnx maestro load <flow>             # load flow into runner without running (--dry-run)
   rnx maestro test .maestro/          # every *.yaml / *.yml in a directory
   rnx maestro generate "<goal>"       # generate, run, and upload a Maestro flow
   rnx maestro start|keep|end          # author a flow from live CLI actions
@@ -46,9 +57,31 @@ usage:
   rnx maestro --list-compat           # print supported/unsupported verbs
 
 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)
+                         JUNIT, NOOP also accepted (case-insensitive)
+  --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
+  --flatten-debug-output accepted; rnx output is already flat
+  --test-suite-name <n>  junit testsuite name (default "Test Suite")
+  --platform ios         accepted; any other platform is refused (rnx is iOS-only)
+                         (-p stays the rnx bridge-port short)
+  --no-ansi              accepted; rnx output is already plain text
+  --udid <id>            warned; rnx manages its own sim (pin one with --sim)
+  -s, --shards <n>       warned; rnx runs the full selection on one sim
+  --shard-all, --shard-split <spec>
+                         warned; rnx runs the full selection on one sim
+  -c                     warned; --continuous runs once under rnx
   --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,
@@ -93,8 +126,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
@@ -128,11 +172,13 @@ function looksLikeFlag(s: string): boolean {
 // extract --env KEY=VALUE pairs from argv and apply to process.env for the
 // duration of the run. returns argv with the consumed flags removed so the
 // rest can be forwarded to runFlowPlayback verbatim.
-function applyEnvFlags(args: string[]): string[] {
+export function applyEnvFlags(args: string[]): string[] {
   const out: string[] = []
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--env' || args[i] === '-e') {
-      const kv = args[i + 1]
+    const arg = args[i] as string
+    const inline = arg.startsWith('--env=') ? arg.slice('--env='.length) : null
+    if (arg === '--env' || arg === '-e' || inline !== null) {
+      const kv = inline ?? args[i + 1]
       if (!kv || !kv.includes('=')) {
         throw new Error(`--env expects KEY=VALUE (got ${JSON.stringify(kv ?? '')})`)
       }
@@ -140,27 +186,150 @@ function applyEnvFlags(args: string[]): string[] {
       const key = kv.slice(0, eq)
       const value = kv.slice(eq + 1)
       process.env[key] = value
-      i += 1
+      if (inline === null) i += 1
       continue
     }
-    out.push(args[i])
+    out.push(arg)
   }
   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
+  testSuiteName: string | null
+}
+
+const MAESTRO_COMPAT_VALUE_FLAGS = new Set([
+  '--include-tags',
+  '--exclude-tags',
+  '--config',
+  '--format',
+  '--output',
+  '--test-output-dir',
+  '--debug-output',
+  '--platform',
+  '--udid',
+  '--test-suite-name',
+  '--shards',
+  '--shard-all',
+  '--shard-split',
+  '--api-key',
+  '--api-url',
+  '--screen-size',
+])
+
+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,
+    testSuiteName: 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':
+          // maestro spells it JUNIT; normalize so either case works.
+          compat.format = value.toLowerCase()
+          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
+        case '--udid':
+          console.warn(
+            '  warn: --udid selects a Maestro simulator; rnx manages its own sim — pin one with --sim instead',
+          )
+          break
+        case '--test-suite-name':
+          compat.testSuiteName = value
+          break
+        case '--shards':
+        case '--shard-all':
+        case '--shard-split':
+          console.warn(
+            `  warn: ${head} shards across Maestro devices; rnx runs the full selection on one sim`,
+          )
+          break
+        case '--api-key':
+        case '--api-url':
+          console.warn(`  warn: ${head} is Maestro beta AI analysis; rnx ignores it`)
+          break
+        case '--screen-size':
+          console.warn('  warn: --screen-size is web-only; rnx ignores it')
+          break
+      }
       continue
     }
     if (a === '--origin') {
@@ -172,16 +341,66 @@ 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' || a === '--no-color') {
+      // trivially satisfied: rnx prints no ANSI escapes anywhere on this path.
+      continue
+    }
+    if (a === '--ansi' || a === '--color') {
+      console.warn('  warn: rnx prints no ANSI escapes; colored output is unavailable')
       continue
     }
-    if (a === '--continuous') {
+    if (a === '--continuous' || a === '-c') {
       console.warn('  warn: --continuous is not implemented in rnx — running once')
       continue
     }
-    out.push(a)
+    if (a === '--flatten-debug-output') {
+      // rnx writes one <dir>/maestro.log with no per-run subfolders or
+      // timestamps, so the maestro layout flag is already satisfied.
+      continue
+    }
+    if (a === '--analyze') {
+      console.warn('  warn: --analyze is Maestro beta AI analysis; rnx ignores it')
+      continue
+    }
+    if (a === '-s') {
+      const count = args[i + 1]
+      if (!count || count.startsWith('-')) throw new Error('-s expects a value')
+      i += 1
+      console.warn(
+        '  warn: -s shards across Maestro devices; rnx runs the full selection on one sim',
+      )
+      continue
+    }
+    if (head === '-p') {
+      // -p is the rnx bridge-port short, not maestro's --platform short. a
+      // non-numeric value is a pasted maestro command line; fail loud with
+      // the mapping instead of pinning the bridge to a NaN port.
+      const value = eq > 0 ? a.slice(eq + 1) : args[i + 1]
+      if (value !== undefined && !value.startsWith('-') && !/^\d+$/.test(value)) {
+        throw new Error(
+          `-p is the rnx bridge-port short; use --platform for the Maestro platform (got ${JSON.stringify(value)})`,
+        )
+      }
+      rest.push(a)
+      continue
+    }
+    rest.push(a)
   }
-  return out
+  if (
+    compat.format !== null &&
+    !['junit', 'html', 'html-detailed', 'noop'].includes(compat.format)
+  ) {
+    throw new Error(`unsupported --format: ${compat.format} (rnx writes junit reports)`)
+  }
+  if (compat.format === 'html' || compat.format === 'html-detailed') {
+    console.warn(
+      '  warn: --format html is not implemented in rnx — running without a report',
+    )
+  }
+  return { rest, compat }
 }
 
 function findDefaultMaestroTarget(cwd: string): string | null {
@@ -196,36 +415,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
@@ -234,17 +505,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'))
@@ -259,6 +535,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 })
@@ -316,7 +609,15 @@ export async function runMaestro(
   remaining = hoistLeadingSimFlag(remaining)
 
   const cwd = process.cwd()
-  const sub = remaining[0]
+  let sub = remaining[0]
+
+  if (sub === 'load') {
+    remaining[0] = 'test'
+    sub = 'test'
+    if (!remaining.includes('--dry-run') && !remaining.includes('--no-run')) {
+      remaining.push('--dry-run')
+    }
+  }
 
   if (sub === 'init') {
     return runInit(cwd)
@@ -335,11 +636,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
@@ -358,6 +675,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
@@ -401,18 +723,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) || '.'}
@@ -435,11 +781,36 @@ export async function runMaestro(
       flagValue('--preview-origin') ?? originFlagValue,
     ))
 
+  const sessionStartedAt = new Date().toISOString()
   let worstExit = 0
-  const results: Array<{ file: string; exit: number }> = []
-  for (const file of files) {
+  const results: Array<{
+    file: string
+    exit: number
+    durationMs: number
+    steps: ReturnType<typeof getLastFlowTraceSteps>
+    frontmatter: FlowFrontmatter
+  }> = []
+  for (const [flowIndex, file] of files.entries()) {
     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
@@ -466,28 +837,63 @@ 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
 
-    const upload = getLastFlowPreviewUploadResult()
-    if (upload?.shareId || upload?.previewUrl) {
+    if (flowTestDir) {
       try {
         fs.writeFileSync(
-          path.join(cwd, 'preview-result.json'),
-          JSON.stringify({
-            previewId: upload.shareId,
-            previewUrl: upload.previewUrl,
-          }),
+          path.join(flowTestDir, 'commands.json'),
+          buildFlowCommandsJson(traceSteps),
         )
-      } catch {}
-    } else if (args.includes('--preview')) {
+        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()
+    // the receipt files are the per-flow manifest: always written, with
+    // null ids when the upload failed, so the flow never disappears from
+    // the collected entries.
+    const previewPayload = {
+      flow: path.relative(cwd, file) || file,
+      previewId: upload?.shareId ?? null,
+      previewUrl: upload?.previewUrl ?? null,
+    }
+    try {
+      for (const name of cloudTestResultFileNames('preview', flowIndex, files.length)) {
+        fs.writeFileSync(path.join(cwd, name), JSON.stringify(previewPayload))
+      }
+    } catch {}
+    if (!upload?.shareId && !upload?.previewUrl && args.includes('--preview')) {
       console.error('  error: required hosted recording upload failed')
       if (exit === 0) exit = 1
       if (worstExit === 0) worstExit = 1
     }
 
     if (shouldRegisterRun({ uploadedShare: Boolean(upload), auth })) {
-      const traceSteps = getLastFlowTraceSteps()
       const failedStep = traceSteps.find((step) => step.status === 'failure')
       const run = await registerRun({
         origin: await registerOrigin(),
@@ -504,22 +910,28 @@ export async function runMaestro(
       })
       if (run) {
         console.log(`  run: ${run.id}${run.traceUrl ? ` · replay: ${run.traceUrl}` : ''}`)
-        try {
-          fs.writeFileSync(
-            path.join(cwd, 'test-result.json'),
-            JSON.stringify({
-              runId: run.id,
-              previewUrl: run.previewUrl,
-              traceUrl: run.traceUrl,
-            }),
-          )
-        } catch {}
       } else if (process.env.RNX_REQUIRE_REGISTRATION === 'true') {
         console.error('  error: required hosted run registration failed')
         if (exit === 0) exit = 1
         if (worstExit === 0) worstExit = 1
       }
+      // like the preview receipt above: always written, null ids when the
+      // registration failed, so the flow keeps its collected entry.
+      const testPayload = {
+        flow: path.relative(cwd, file) || file,
+        runId: run?.id ?? null,
+        previewUrl: run?.previewUrl ?? null,
+        traceUrl: run?.traceUrl ?? null,
+      }
+      try {
+        for (const name of cloudTestResultFileNames('test', flowIndex, files.length)) {
+          fs.writeFileSync(path.join(cwd, name), JSON.stringify(testPayload))
+        }
+      } catch {}
     }
+    // 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) {
@@ -532,5 +944,106 @@ 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)),
+          ...(compat.testSuiteName ? { name: compat.testSuiteName } : {}),
+        }),
+      )
+      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'),
+  }
+}