@capagents/forgeqe 1.3.1 → 2.0.0

package/src/mobile/command.ts

@@ -0,0 +1,245 @@
+import { spawnSync } from "node:child_process"
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { boolFlag, configOpts, strFlag, type Flags } from "../cli/args.ts"
+import { terminalAsk } from "../cli/terminal.ts"
+import { loadConfig, type AppConfig } from "../config.ts"
+import type { DesktopEvent } from "../desktop/bridge.ts"
+import { abortOnSigint, color, offerHeals, printer, splitReplayArgs, workflowFiles } from "../desktop/command.ts"
+import { junitXml, type JunitCase } from "../desktop/junit.ts"
+import { parseCsv, visionProblem } from "../desktop/run.ts"
+import { engineEnv, ensureEngine } from "../engine/setup.ts"
+import { withEnvironment } from "../environments.ts"
+import { checkMobileApp, checkMobileConfig, exploreMobile, hasModel, maestroFlowFiles, mobileDoctor, mobileOutDir, replayMobile, runMaestroFlows, uploadToTestmu } from "./run.ts"
+
+/** `forgeqe mobile`: Android and iOS apps through Appium or Maestro (docs/MOBILE.md). */
+
+export const MOBILE_USAGE = `Usage:
+  forgeqe mobile apps [--env NAME]               the mobile apps of the environment (env.yaml) and mobile:
+  forgeqe mobile doctor                          whether the Appium server answers and maestro is installed
+  forgeqe mobile explore "<goal>" --app NAME [--name TEXT] [--out DIR] [--yes]
+                                                 the model does the goal in the app through Appium; what it did is
+                                                 saved as workflow.yaml, with checks of the outcome
+  forgeqe mobile replay <workflow.yaml|folder> ... [name=value ...] [--driver appium|maestro] [--data rows.csv]
+                        [--no-heal] [--accept-heals] [--update-baselines] [--junit results.xml] [--out DIR]
+                                                 replay mobile workflows with no model (Appium heals a moved control)
+  forgeqe mobile maestro <flow.yaml|folder> ... [--junit results.xml] [--out DIR]
+                                                 run your team's Maestro flows, after checking them against the allowlist
+  forgeqe mobile upload <app.apk|.ipa> [--name TEXT] [--virtual]
+                                                 upload a build to TestMu AI; prints the lt:// id for the app's \`app\`
+  forgeqe mobile flow <workflow.yaml>            print a mobile workflow as a Maestro flow
+  forgeqe mobile validate <workflow.yaml>        check a workflow without running it`
+
+function config(flags: Flags): AppConfig {
+  const cfg = loadConfig(configOpts(flags))
+  checkMobileConfig(cfg)
+  return cfg
+}
+
+function driverFlag(flags: Flags): "appium" | "maestro" | undefined {
+  const d = strFlag(flags, "driver")
+  if (d === undefined) return undefined
+  if (d !== "appium" && d !== "maestro") throw new Error("--driver must be appium or maestro")
+  return d
+}
+
+async function cmdReplay(args: string[], flags: Flags): Promise<number> {
+  const { paths, variables } = splitReplayArgs(args)
+  if (!paths.length) throw new Error(MOBILE_USAGE)
+  const workflows = workflowFiles(paths, process.cwd(), "mobile")
+  const dataFile = strFlag(flags, "data")
+  const rows = dataFile ? parseCsv(readFileSync(path.resolve(dataFile), "utf8")) : [{}]
+  if (!rows.length) throw new Error(`${dataFile} has a header but no rows`)
+  const cfg = config(flags)
+  const driver = driverFlag(flags) || cfg.mobile.driver
+  const heal = cfg.mobile.heal && !boolFlag(flags, "no-heal")
+  if (driver === "appium" && heal && !hasModel(cfg)) console.error("Note: no model in llms.json, so moved controls will not be healed.")
+  const outDir = mobileOutDir(cfg, "replay", strFlag(flags, "out"))
+  const { signal, done } = abortOnSigint()
+  const cases: JunitCase[] = []
+  let failed = 0
+  try {
+    for (const workflow of workflows) {
+      const label = path.relative(process.cwd(), workflow) || workflow
+      if (workflows.length > 1) console.log(`\n${label}`)
+      let offered = false
+      for (let i = 0; i < rows.length; i++) {
+        if (signal.aborted) break
+        const dir = workflows.length * rows.length > 1 ? mobileOutDir(cfg, "replay", path.join(outDir, `${path.basename(workflow).replace(/\.ya?ml$/i, "")}${rows.length > 1 ? `-row-${String(i + 1).padStart(3, "0")}` : ""}`)) : outDir
+        const started = Date.now()
+        const run = await replayMobile({ cfg, workflow, variables: { ...variables, ...rows[i] }, heal, driver, updateBaselines: boolFlag(flags, "update-baselines"), outDir: dir, signal, onEvent: printer(color()), log: (t) => console.error(t) })
+        const bad = (run.result.steps || []).find((s) => !s.ok)
+        const error = run.result.error || (bad ? `step ${bad.index} (${bad.op}): ${bad.error || "failed"}` : run.result.ok ? "" : "failed")
+        if (run.result.error) console.error(run.result.error)
+        console.log(`report  ${run.report}`)
+        if (!run.result.ok) failed++
+        cases.push({ suite: label, name: `${run.result.name || path.basename(workflow)}${rows.length > 1 ? ` (row ${i + 1})` : ""}`, ok: run.result.ok, seconds: (Date.now() - started) / 1000, ...(error ? { error } : {}), report: run.report })
+        if (run.result.heals?.length && !offered) {
+          offered = true
+          await offerHeals(workflow, dir, run.result.heals, flags, signal)
+        }
+      }
+    }
+    writeJunit(flags, cases)
+    const planned = workflows.length * rows.length
+    if (planned > 1) console.log(`\n${cases.length - failed} of ${planned} runs passed`)
+    return cases.length === planned && failed === 0 ? 0 : 1
+  } finally {
+    done()
+  }
+}
+
+function writeJunit(flags: Flags, cases: JunitCase[]): void {
+  const junit = strFlag(flags, "junit")
+  if (!junit) return
+  const file = path.resolve(junit)
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, junitXml(cases, "forgeqe mobile"))
+  console.log(`junit   ${file}`)
+}
+
+async function cmdMaestro(args: string[], flags: Flags): Promise<number> {
+  if (!args.length) throw new Error(MOBILE_USAGE)
+  const cfg = config(flags)
+  const root = process.cwd()
+  const flows = maestroFlowFiles(args, root)
+  const outDir = mobileOutDir(cfg, "maestro", strFlag(flags, "out"))
+  const { signal, done } = abortOnSigint()
+  try {
+    const started = Date.now()
+    const { result, report } = await runMaestroFlows({ cfg, flows, root, outDir, signal, onEvent: printer(color()), log: (t) => console.error(t) })
+    for (const f of result.flows || []) console.log(`${f.ok ? "✓" : "✗"} ${f.name}${f.error ? `: ${f.error}` : ""}`)
+    if (result.error) console.error(result.error)
+    console.log(`report  ${report}`)
+    const seconds = (Date.now() - started) / 1000
+    writeJunit(flags, (result.flows || []).map((f) => ({ suite: "maestro", name: f.name, ok: f.ok, seconds: seconds / Math.max(1, (result.flows || []).length), ...(f.error ? { error: f.error } : {}), report })))
+    return result.ok ? 0 : 1
+  } finally {
+    done()
+  }
+}
+
+async function cmdExplore(args: string[], flags: Flags): Promise<number> {
+  const goal = args.join(" ").trim()
+  const app = strFlag(flags, "app")
+  if (!goal || !app) throw new Error(MOBILE_USAGE)
+  const cfg = config(flags)
+  checkMobileApp(cfg, app)
+  if (!hasModel(cfg)) throw new Error("No model is set up in llms.json. Run: forgeqe init, then forgeqe models.")
+  const problem = visionProblem(cfg.activeProfile, cfg.llm)
+  if (problem) throw new Error(problem.replace("the desktop agent", "the mobile agent"))
+  const { signal, done } = abortOnSigint()
+  try {
+    if (!boolFlag(flags, "yes")) {
+      const ask = terminalAsk(signal)
+      if (!ask) throw new Error("explore acts in the app on a real device or emulator; pass --yes to run it without a terminal to confirm in.")
+      const answer = await ask({
+        title: `The mobile agent will operate ${app} to: ${goal}`,
+        detail: `It acts in the app through Appium (${cfg.mobile.appium.url}), and its model is ${cfg.activeProfile}. Use a test device and a test account.`,
+        options: [
+          { id: "no", label: "Cancel" },
+          { id: "yes", label: "Start" },
+        ],
+      })
+      if (answer !== "yes") return 1
+    }
+    const outDir = mobileOutDir(cfg, "explore", strFlag(flags, "out"))
+    const onEvent = (ev: DesktopEvent) => {
+      if (ev.type === "step") console.log(`● ${String(ev.index).padStart(3)} ${ev.op}${ev.target ? ` ${String(ev.target.name || ev.target.automation_id || "")}` : ""}`)
+      else printer(color())(ev)
+    }
+    const { result, report } = await exploreMobile({ cfg, goal, app, name: strFlag(flags, "name"), outDir, signal, onEvent, log: (t) => console.error(t) })
+    if (result.error) console.error(result.error)
+    console.log(`\nreport   ${report}`)
+    if (result.workflow) {
+      console.log(`workflow ${result.workflow} (${result.recorded} steps, ${result.checks ?? 0} checks)`)
+      console.log(`replay   forgeqe mobile replay "${result.workflow}"   (or --driver maestro)`)
+    }
+    return result.ok ? 0 : 1
+  } finally {
+    done()
+  }
+}
+
+async function cmdFlow(args: string[], flags: Flags): Promise<number> {
+  const file = args[0]
+  if (!file) throw new Error(MOBILE_USAGE)
+  const cfg = config(flags)
+  const app = String((readFileSync(path.resolve(file), "utf8").match(/^app:\s*["']?([A-Za-z0-9_.-]+)/m) || [])[1] || "")
+  checkMobileApp(cfg, app)
+  const raw = cfg.mobile.apps[app] as { app_id?: string }
+  const python = await ensureEngine((t) => console.error(t))
+  const r = spawnSync(python, ["-m", "forgeqe_mobile", "flow", path.resolve(file), "--app-id", String(raw.app_id || "")], { env: engineEnv(), encoding: "utf8" })
+  if (r.error) throw r.error
+  process.stdout.write(r.stdout || "")
+  process.stderr.write(r.stderr || "")
+  return r.status ?? 1
+}
+
+async function cmdValidate(args: string[]): Promise<number> {
+  const file = args[0]
+  if (!file) throw new Error(MOBILE_USAGE)
+  const python = await ensureEngine((t) => console.error(t))
+  const r = spawnSync(python, ["-m", "forgeqe_desktop", "validate", path.resolve(file)], { env: engineEnv(), encoding: "utf8" })
+  if (r.error) throw r.error
+  process.stdout.write(r.stdout || "")
+  process.stderr.write(r.stderr || "")
+  return r.status ?? 1
+}
+
+async function cmdDoctor(flags: Flags): Promise<number> {
+  const cfg = config(flags)
+  const d = await mobileDoctor(cfg, (t) => console.error(t))
+  if (d.error) console.log(`engine   not ready (${d.error})`)
+  console.log(`appium   ${d.appium ? `answers at ${d.appiumUrl}${d.appiumVersion ? ` (Appium ${d.appiumVersion})` : ""}` : `no answer at ${d.appiumUrl}${d.appiumError ? ` (${d.appiumError})` : ""}; start it with: appium`}`)
+  console.log(`maestro  ${d.maestro ? `installed (${d.maestroPath})` : "not installed (https://maestro.mobile.dev)"}`)
+  console.log(`driver   ${cfg.mobile.driver} (mobile.driver; --driver on replay)`)
+  return (cfg.mobile.driver === "appium" ? d.appium : d.maestro) ? 0 : 1
+}
+
+function cmdApps(flags: Flags): number {
+  const cfg = withEnvironment(config(flags), strFlag(flags, "env"))
+  const apps = Object.entries(cfg.mobile.apps)
+  if (!apps.length) {
+    console.log("No mobile apps. Add one to env.yaml (kind: mobile) or forgeqe.yaml:\n\nmobile:\n  apps:\n    courier:\n      platform: android\n      app_id: com.contoso.courier\n      activity: .MainActivity\n  secrets: [COURIER_PASSWORD]")
+    return 0
+  }
+  for (const [name, raw] of apps) {
+    const r = (raw && typeof raw === "object" ? raw : {}) as { platform?: string; app_id?: string; activity?: string; app?: string }
+    console.log(`${name.padEnd(16)} ${String(r.platform || "?")} ${String(r.app_id || "")}${r.activity ? ` ${r.activity}` : ""}${r.app ? `  (installs ${r.app})` : ""}`)
+  }
+  console.log(`\nsecrets  ${cfg.mobile.secrets.join(", ") || "none"}`)
+  console.log(`driver   ${cfg.mobile.driver}; appium ${cfg.mobile.appium.url}`)
+  return 0
+}
+
+export async function cmdMobile(args: string[], flags: Flags): Promise<number> {
+  const [sub, ...rest] = args
+  switch (sub) {
+    case "apps":
+      return cmdApps(flags)
+    case "doctor":
+      return cmdDoctor(flags)
+    case "explore":
+      return cmdExplore(rest, flags)
+    case "replay":
+      return cmdReplay(rest, flags)
+    case "maestro":
+      return cmdMaestro(rest, flags)
+    case "flow":
+      return cmdFlow(rest, flags)
+    case "upload": {
+      if (!rest[0]) throw new Error(MOBILE_USAGE)
+      const id = await uploadToTestmu(config(flags), rest[0], { name: strFlag(flags, "name"), virtual: boolFlag(flags, "virtual") })
+      console.log(id)
+      console.error(`Put it in the mobile app's app: (env.yaml or forgeqe.yaml); ForgeQE gives it to Appium (LT:Options) and to Maestro on TestMu itself.`)
+      return 0
+    }
+    case "validate":
+      return cmdValidate(rest)
+    default:
+      console.log(MOBILE_USAGE)
+      return sub ? 2 : 0
+  }
+}

package/src/mobile/run.ts

@@ -0,0 +1,226 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig, MobileConfig } from "../config.ts"
+import { runEngine, type DesktopEvent, type DesktopResult } from "../desktop/bridge.ts"
+import { writeDesktopReport } from "../desktop/report.ts"
+import { AZURE_IDENTITY_ENV } from "../entra.ts"
+import { llmPayload } from "../engine/bridge.ts"
+import { engineEnv, ensureEngine } from "../engine/setup.ts"
+import { privateEnvNames } from "../childEnv.ts"
+
+/**
+ * Mobile apps (Android, iOS) as the CLI (`forgeqe mobile`) and ForgeQE's agent (mobile_* tools) run them: through the
+ * mobile engine (`python -m forgeqe_mobile serve`, in the browser engine's Python), on Appium or Maestro. docs/MOBILE.md.
+ */
+
+export type MobileRun = { result: DesktopResult; report: string; outDir: string }
+type Common = { cfg: AppConfig; outDir: string; signal?: AbortSignal; onEvent?: (e: DesktopEvent) => void; log?: (t: string) => void }
+
+/** mobile.secrets that are ForgeQE's own (a model key, a tracker token): a workflow may never type those. */
+export function privateMobileSecrets(cfg: AppConfig): string[] {
+  const own = new Set(privateEnvNames(cfg))
+  return cfg.mobile.secrets.filter((n) => own.has(n))
+}
+
+export function checkMobileConfig(cfg: AppConfig): void {
+  const own = privateMobileSecrets(cfg)
+  if (own.length) throw new Error(`mobile.secrets lists ${own.join(", ")}, which ForgeQE itself uses (a model key or a service token); a workflow may not type it.`)
+}
+
+export function checkMobileApp(cfg: AppConfig, app: string): void {
+  if (!Object.prototype.hasOwnProperty.call(cfg.mobile.apps, app)) {
+    throw new Error(`App "${app}" is not a mobile app of this environment or of forgeqe.yaml mobile.apps (configured: ${Object.keys(cfg.mobile.apps).join(", ") || "none"}).`)
+  }
+}
+
+/** The engine's view of mobile: config, with the cloud credentials as names only. */
+export function mobilePayload(m: MobileConfig): Record<string, unknown> {
+  return {
+    apps: m.apps,
+    secrets: m.secrets,
+    driver: m.driver,
+    screenshots: m.screenshots,
+    appium: { url: m.appium.url, capabilities: m.appium.capabilities, ...(m.appium.usernameEnv ? { username_env: m.appium.usernameEnv } : {}), ...(m.appium.accessKeyEnv ? { access_key_env: m.appium.accessKeyEnv } : {}) },
+    maestro: {
+      command: m.maestro.command,
+      ...(m.maestro.device ? { device: m.maestro.device } : {}),
+      ...(m.maestro.testmu
+        ? { testmu: { cli: m.maestro.testmu.cli, devices: m.maestro.testmu.devices, real_device: m.maestro.testmu.realDevice, ...(m.maestro.testmu.region ? { region: m.maestro.testmu.region } : {}), username_env: m.maestro.testmu.usernameEnv, access_key_env: m.maestro.testmu.accessKeyEnv } }
+        : {}),
+    },
+  }
+}
+
+/** What the engine process may see besides system settings: the model's key, mobile.secrets, the cloud's user and key,
+ * and the Android and Java settings Maestro and Appium need. */
+export function mobileEnvNames(cfg: AppConfig): string[] {
+  const llm = cfg.llm
+  return [...new Set([
+    ...(llm.auth === "entra" ? AZURE_IDENTITY_ENV : llm.apiKeyEnv ? [llm.apiKeyEnv] : []),
+    ...cfg.mobile.secrets,
+    ...[cfg.mobile.appium.usernameEnv, cfg.mobile.appium.accessKeyEnv, cfg.mobile.maestro.testmu?.usernameEnv, cfg.mobile.maestro.testmu?.accessKeyEnv].filter((n): n is string => Boolean(n)),
+    "JAVA_HOME",
+    "ANDROID_HOME",
+    "ANDROID_SDK_ROOT",
+    "MAESTRO_CLI_NO_ANALYTICS",
+  ])]
+}
+
+function stamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19)
+}
+
+export function mobileOutDir(cfg: AppConfig, kind: "explore" | "replay" | "maestro", out?: string): string {
+  const dir = out ? path.resolve(out) : path.join(cfg.export.outDir, `mobile-${kind}-${stamp()}`)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+function modelLabel(cfg: AppConfig): string {
+  return `${cfg.activeProfile} (${cfg.llm.provider}/${cfg.llm.deployment || cfg.llm.model})`
+}
+
+async function run(opts: Common, payload: Record<string, unknown>): Promise<MobileRun> {
+  const python = await ensureEngine(opts.log || (() => {}))
+  const full = { ...payload, out_dir: opts.outDir, llm: llmPayload(opts.cfg.llm), profile_name: opts.cfg.activeProfile, mobile: mobilePayload(opts.cfg.mobile) }
+  const result = await runEngine({
+    command: [python, "-m", "forgeqe_mobile", "serve"],
+    payload: full,
+    logged: { ...payload, mobile: { apps: Object.keys(opts.cfg.mobile.apps), secrets: opts.cfg.mobile.secrets, driver: opts.cfg.mobile.driver, appium: opts.cfg.mobile.appium.url } },
+    envNames: mobileEnvNames(opts.cfg),
+    outDir: opts.outDir,
+    llm: opts.cfg.llm,
+    agent: "mobile agent",
+    log: "mobile",
+    signal: opts.signal,
+    onEvent: opts.onEvent,
+  })
+  const report = writeDesktopReport(opts.outDir, result, { model: modelLabel(opts.cfg), kind: "Mobile", ...(opts.cfg.environments?.active ? { environment: opts.cfg.environments.active } : {}) })
+  if (result.heals?.length) writeFileSync(path.join(opts.outDir, "heals.json"), JSON.stringify(result.heals, null, 2))
+  return { result, report, outDir: opts.outDir }
+}
+
+export function hasModel(cfg: AppConfig): boolean {
+  return Boolean(cfg.llm.model) && cfg.llm.provider !== "none" && cfg.llm.provider !== "mock"
+}
+
+/** Replay a mobile workflow on Appium (step by step, healing a moved control) or Maestro. */
+export function replayMobile(opts: Common & { workflow: string; variables?: Record<string, string>; heal: boolean; driver?: "appium" | "maestro"; updateBaselines?: boolean }): Promise<MobileRun> {
+  const driver = opts.driver || opts.cfg.mobile.driver
+  return run(opts, {
+    mode: "replay",
+    workflow: opts.workflow,
+    variables: opts.variables || {},
+    driver,
+    heal: driver === "appium" && opts.heal && hasModel(opts.cfg),
+    update_baselines: Boolean(opts.updateBaselines),
+  })
+}
+
+/** The model carries out a goal in the app through Appium; what it did is saved as workflow.yaml, with checks. */
+export function exploreMobile(opts: Common & { goal: string; app: string; name?: string }): Promise<MobileRun> {
+  return run(opts, { mode: "explore", goal: opts.goal, app: opts.app, ...(opts.name ? { name: opts.name } : {}) })
+}
+
+/** The team's own Maestro flows, checked against the allowlist, then run. */
+export function runMaestroFlows(opts: Common & { flows: string[]; root: string }): Promise<MobileRun> {
+  return run(opts, { mode: "maestro", flows: opts.flows, root: opts.root })
+}
+
+/** Maestro flow files a caller names, as real paths inside `root`: .yaml files, and the flows directly in a folder. */
+export function maestroFlowFiles(paths: string[], root: string): string[] {
+  const realRoot = realpathSync(root)
+  const inside = (p: string) => {
+    const rel = path.relative(realRoot, p)
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel)
+  }
+  const out: string[] = []
+  for (const p of paths) {
+    const full = path.resolve(root, p)
+    if (!existsSync(full)) throw new Error(`No flow at ${full}`)
+    const real = realpathSync(full)
+    if (!inside(real) && real !== realRoot) throw new Error(`${p} is outside the working folder; Maestro flows are read from it only.`)
+    if (statSync(real).isDirectory()) {
+      const found = readdirSync(real)
+        .filter((f) => /\.ya?ml$/i.test(f) && !f.startsWith("."))
+        .sort()
+        .map((f) => path.join(real, f))
+        .filter((f) => statSync(f).isFile() && /^appId:/m.test(readFileSync(f, "utf8")))
+      if (!found.length) throw new Error(`${full} has no Maestro flows (.yaml files with appId:)`)
+      out.push(...found)
+    } else if (/\.ya?ml$/i.test(real)) out.push(real)
+    else throw new Error(`${p} is not a Maestro flow (.yaml)`)
+  }
+  return [...new Set(out)]
+}
+
+export type MobileDoctor = { python?: string; appium: boolean; appiumUrl: string; appiumVersion?: string; appiumError?: string; maestro: boolean; maestroPath?: string; error?: string }
+
+/** Whether the Appium server answers and maestro is installed. */
+export async function mobileDoctor(cfg: AppConfig, log: (t: string) => void = () => {}): Promise<MobileDoctor> {
+  let python: string
+  try {
+    python = await ensureEngine(log)
+  } catch (e) {
+    return { appium: false, appiumUrl: cfg.mobile.appium.url, maestro: false, error: (e as Error).message }
+  }
+  const r = spawnSync(python, ["-m", "forgeqe_mobile", "doctor", "--appium-url", cfg.mobile.appium.url, "--maestro", cfg.mobile.maestro.command[0]!], { env: engineEnv({}, mobileEnvNames(cfg)), encoding: "utf8" })
+  try {
+    const d = JSON.parse((r.stdout || "").trim().split(/\r?\n/).pop() || "{}") as Record<string, unknown>
+    return {
+      python,
+      appium: d.appium === true,
+      appiumUrl: cfg.mobile.appium.url,
+      ...(d.appium_version ? { appiumVersion: String(d.appium_version) } : {}),
+      ...(d.appium_error ? { appiumError: String(d.appium_error) } : {}),
+      maestro: d.maestro === true,
+      ...(d.maestro_path ? { maestroPath: String(d.maestro_path) } : {}),
+    }
+  } catch {
+    return { python, appium: false, appiumUrl: cfg.mobile.appium.url, maestro: false, error: (r.stderr || "the check did not run").trim().split(/\r?\n/).pop() }
+  }
+}
+
+/** TestMu AI's app upload: real devices, or its emulators and simulators. */
+export const TESTMU_UPLOAD = {
+  real: "https://manual-api.lambdatest.com/app/upload/realDevice",
+  virtual: "https://manual-api.lambdatest.com/app/upload/virtualDevice",
+} as const
+
+/**
+ * Upload an app build to TestMu AI and return its lt:// id, for the mobile app's `app`. The user and key come from the
+ * variables mobile.appium (or mobile.maestro.testmu) names, LT_USERNAME and LT_ACCESS_KEY by default.
+ */
+export async function uploadToTestmu(cfg: AppConfig, file: string, opts: { name?: string; virtual?: boolean; fetch?: typeof fetch } = {}): Promise<string> {
+  const full = path.resolve(file)
+  if (!/\.(apk|aab|ipa|zip)$/i.test(full)) throw new Error(`${file} is not an app build (.apk, .aab, .ipa or .zip).`)
+  if (!existsSync(full) || !statSync(full).isFile()) throw new Error(`No app build at ${full}`)
+  const userEnv = cfg.mobile.maestro.testmu?.usernameEnv || cfg.mobile.appium.usernameEnv || "LT_USERNAME"
+  const keyEnv = cfg.mobile.maestro.testmu?.accessKeyEnv || cfg.mobile.appium.accessKeyEnv || "LT_ACCESS_KEY"
+  const user = process.env[userEnv]
+  const key = process.env[keyEnv]
+  if (!user || !key) throw new Error(`Set ${userEnv} and ${keyEnv} (your TestMu user name and access key), for example in .env in this folder.`)
+  const form = new FormData()
+  form.append("appFile", new Blob([readFileSync(full)]), path.basename(full))
+  form.append("name", (opts.name || path.basename(full)).replace(/[^A-Za-z0-9 ._-]/g, "_").slice(0, 100))
+  const res = await (opts.fetch || fetch)(opts.virtual ? TESTMU_UPLOAD.virtual : TESTMU_UPLOAD.real, {
+    method: "POST",
+    headers: { authorization: `Basic ${Buffer.from(`${user}:${key}`).toString("base64")}` },
+    body: form,
+  })
+  const text = await res.text()
+  let doc: { app_url?: unknown; message?: unknown; error?: unknown } = {}
+  try {
+    doc = JSON.parse(text)
+  } catch {
+    // reported below
+  }
+  const appUrl = typeof doc.app_url === "string" ? doc.app_url : ""
+  if (!res.ok || !/^lt:\/\/[A-Za-z0-9]+$/.test(appUrl)) {
+    const why = String(doc.message || doc.error || text || res.statusText).split(key).join("***").slice(0, 300)
+    throw new Error(`TestMu did not take the upload (${res.status}): ${why}`)
+  }
+  return appUrl
+}

package/src/pack/pipeline.ts

@@ -8,6 +8,7 @@ import { http } from "../cases/http.ts"
 import { parseResults, type TestOutcome, type TestsRun } from "../code/find.ts"
 import { walk } from "../code/profile.ts"
 import { runDirectory } from "../run.ts"
+import { environmentVariables } from "../environments.ts"
 import { loadPack, savePack, type Pack, type PackRun } from "./pack.ts"
 import { WS_ENDPOINT_ENV } from "./run.ts"
 
@@ -72,6 +73,28 @@ function testCommands(framework: Framework, dotnet?: { project: string; settings
 }
 
 /** A GitHub Actions workflow that runs a pack: dispatched by ForgeQE with the pack's selector and target. */
+/**
+ * The test environment's FORGEQE_* values (src/environments.ts) into the job's environment, from the env_vars input:
+ * only FORGEQE_ names, and no value with a line break, so an input can never set another variable.
+ */
+const ENV_VARS_SCRIPT = [
+  "python3 - <<'PY' >> {OUT}",
+  "import json, os, re",
+  "for k, v in json.loads(os.environ.get('ENV_VARS') or '{}').items():",
+  "    if re.fullmatch(r'FORGEQE_[A-Z0-9_]+', k) and isinstance(v, str) and not re.search(r'[\\r\\n]', v):",
+  "        print({LINE})",
+  "PY",
+].join("\n")
+
+/** Whether a pipeline file ForgeQE wrote takes the env_vars input (files written before it do not, and reject it). */
+export function takesEnvVars(file: string): boolean {
+  try {
+    return /\benv_vars\b/.test(readFileSync(file, "utf8"))
+  } catch {
+    return false
+  }
+}
+
 export function githubWorkflow(framework: Framework, remote: BrowserRemoteConfig | undefined, dotnet?: { project: string; settings?: string }): string {
   const t = testCommands(framework, dotnet)
   const setupStep = framework === "dotnet" ? `      - uses: actions/setup-dotnet@v4\n        with:\n          dotnet-version: "9.0.x"` : framework === "playwright" ? `      - uses: actions/setup-node@v4\n        with:\n          node-version: 22` : `      - uses: actions/setup-python@v5\n        with:\n          python-version: "3.12"`
@@ -96,6 +119,10 @@ on:
         type: choice
         options: [local, testmu]
         default: local
+      env_vars:
+        description: The test environment's FORGEQE_* values (env.yaml), as JSON; ForgeQE fills it
+        required: false
+        default: "{}"
 jobs:
   pack:
     runs-on: ubuntu-latest
@@ -115,6 +142,11 @@ ${indent(t.setup.join("\n"), 10)}
           RUN_ID: \${{ inputs.run_id }}
         run: |
 ${indent(endpointScript(remote, '"$GITHUB_ENV"'), 10)}
+      - name: Test environment
+        env:
+          ENV_VARS: \${{ inputs.env_vars }}
+        run: |
+${indent(ENV_VARS_SCRIPT.replace("{OUT}", '"$GITHUB_ENV"').replace("{LINE}", "f\"{k}={v}\""), 10)}
       - name: Run the pack
         env:
           TESTS: \${{ inputs.tests }}
@@ -150,6 +182,9 @@ parameters:
     type: string
     default: local
     values: [local, testmu]
+  - name: env_vars
+    type: string
+    default: "{}"
 pool:
   vmImage: ubuntu-latest
 steps:
@@ -168,6 +203,11 @@ ${indent(endpointScript(remote, "endpoint.env"), 6)}
       LT_ACCESS_KEY: $(LT_ACCESS_KEY)
       PACK: \${{ parameters.pack }}
       RUN_ID: \${{ parameters.run_id }}
+  - script: |
+${indent(ENV_VARS_SCRIPT.replace("{OUT}", "/dev/stdout").replace("{LINE}", "f\"##vso[task.setvariable variable={k}]{v}\""), 6)}
+    displayName: Test environment
+    env:
+      ENV_VARS: \${{ parameters.env_vars }}
   - script: ${t.run}
     displayName: Run the pack
     env:
@@ -269,7 +309,9 @@ export async function runPackOnPipeline(opts: PipelineOpts): Promise<{ pack: Pac
   if (kind === "github") {
     const g = pipe!.github!
     const exec = opts.exec || ghExec
-    const inputs = { pack: pack.name, run_id: runId, tests: selector, target: opts.target }
+    const envVars = environmentVariables(cfg)
+    const withEnv = Object.keys(envVars).length && takesEnvVars(path.join(opts.repo, ".github", "workflows", g.workflow))
+    const inputs = { pack: pack.name, run_id: runId, tests: selector, target: opts.target, ...(withEnv ? { env_vars: JSON.stringify(envVars) } : {}) }
     command = `gh workflow run ${g.workflow} -R ${g.repo} --ref ${g.ref} ${Object.keys(inputs).map((k) => `-f ${k}=…`).join(" ")}`
     const fired = await exec(["workflow", "run", g.workflow, "-R", g.repo, "--ref", g.ref, ...Object.entries(inputs).flatMap(([k, v]) => ["-f", `${k}=${v}`])], opts.repo)
     if (fired.code !== 0) throw new Error(`GitHub did not start ${g.workflow} in ${g.repo}: ${(fired.err || fired.out).trim().slice(0, 300)}`)
@@ -318,7 +360,7 @@ export async function runPackOnPipeline(opts: PipelineOpts): Promise<{ pack: Pac
     command = `Azure DevOps pipeline ${a.pipelineId} in ${a.project} (${a.ref})`
     const { data: queued } = await http<{ id: number; _links?: { web?: { href?: string } } }>(`${base}/_apis/pipelines/${a.pipelineId}/runs?api-version=7.1`, {
       auth,
-      body: { resources: { repositories: { self: { refName: a.ref } } }, templateParameters: { pack: pack.name, run_id: runId, tests: selector, target: opts.target } },
+      body: { resources: { repositories: { self: { refName: a.ref } } }, templateParameters: { pack: pack.name, run_id: runId, tests: selector, target: opts.target, ...(Object.keys(environmentVariables(cfg)).length && takesEnvVars(path.join(opts.repo, ADO_PIPELINE_FILE)) ? { env_vars: JSON.stringify(environmentVariables(cfg)) } : {}) } },
     })
     url = queued?._links?.web?.href || ""
     say(`Queued pipeline run ${queued.id}${url ? ` (${url})` : ""}`)

package/src/refine.ts

@@ -11,6 +11,7 @@ import { allStatuses } from "./capabilities/status.ts"
 import { domainNotes } from "./domain.ts"
 import type { CodeEvent } from "./types.ts"
 import { steScore } from "./ste.ts"
+import { guardrailsNotes } from "./guardrails.ts"
 
 /**
  * The shell's Refine (ctrl+r): what the user typed becomes a precise request for ForgeQE's agent, checked against what
@@ -151,6 +152,8 @@ export async function refine(opts: {
       profile: opts.config.llm,
       // The refiner works on the request, not the domain: ForgeQE's agent applies that when it handles it.
       domain: null,
+      // The refined request is what the agents work to, so it must not ask for anything a guardrail forbids.
+      guardrails: guardrailsNotes(opts.config),
       model: opts.config.code.model,
       bin: opts.config.code.opencode,
       readDirs: [cwd],

package/src/report/html.ts

@@ -14,6 +14,8 @@ export { readTimeline, type TimelineStep } from "./data.ts"
 
 /** Where and how the run happened, shown at the top of the report. */
 export type ReportEnv = {
+  /** The test environment (env.yaml) the run used. */
+  testEnvironment?: string
   model: string
   browser: string
   startUrl?: string
@@ -54,6 +56,7 @@ export function reportEnv(
     ? `${remote.browser} ${remote.browserVersion} on ${remote.platform || [remote.os, remote.osVersion].filter(Boolean).join(" ")} (${opts.browser!.provider}${opts.browser!.device ? `, device ${opts.browser!.device}` : ""})`
     : undefined
   return {
+    ...(config.environments?.active ? { testEnvironment: config.environments.active } : {}),
     model: `${config.activeProfile} (${llm.provider}/${llm.deployment || llm.model})`,
     browser:
       llm.provider === "mock"