@capagents/forgeqe 1.3.2 → 2.0.1

package/src/desktop/command.ts

@@ -0,0 +1,350 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, 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 { engineEnv, ensureEngine } from "../engine/setup.ts"
+import type { DesktopEvent, DesktopResult } from "./bridge.ts"
+import { junitXml, type JunitCase } from "./junit.ts"
+import {
+  applyHeals,
+  checkApp,
+  checkDesktopConfig,
+  desktopOutDir,
+  exploreGoal,
+  hasModel,
+  parseCsv,
+  parseVariables,
+  privateDesktopSecrets,
+  recordByHand,
+  recordingNotes,
+  replayWorkflow,
+  visionProblem,
+} from "./run.ts"
+import { NOT_WINDOWS, desktopDoctor, ensureDesktop, ufoCommit, ufoDir } from "./setup.ts"
+
+/** `forgeqe desktop`: automate Windows thick-client apps (docs/DESKTOP.md). */
+
+export { applyHeals, parseVariables, privateDesktopSecrets, visionProblem }
+
+export const DESKTOP_USAGE = `Usage:
+  forgeqe desktop setup [--ufo] [--force]        set up the desktop engine (Windows); --ufo also fetches the pinned UFO²
+  forgeqe desktop apps [--env NAME]               the desktop apps and secrets of the environment (env.yaml) and desktop:
+  forgeqe desktop validate <workflow.yaml>        check a workflow without running it (any OS)
+  forgeqe desktop explore "<goal>" --app NAME [--name TEXT] [--out DIR] [--yes]
+                                                  UFO² does the goal on the live app; the run, with checks of the
+                                                  outcome, is saved as workflow.yaml
+  forgeqe desktop record --app NAME [--name TEXT] [--out DIR]
+                                                  you do the steps in the app; your clicks and keys are saved as
+                                                  workflow.yaml (no model). Ctrl+Shift+F11 adds a check of the control
+                                                  under the mouse; Ctrl+Shift+F12 or closing the app stops
+  forgeqe desktop replay <workflow.yaml|folder> ... [name=value ...] [--data rows.csv] [--no-heal] [--accept-heals]
+                        [--update-baselines] [--junit results.xml] [--out DIR]
+                                                  replay workflows with no model (a folder: each workflow in it; once
+                                                  per CSV row with --data); a step whose control moved is healed;
+                                                  --junit writes the results for CI
+  forgeqe desktop doctor                          whether replay can run here unattended (engine, unlocked session)`
+
+export function printer(color: boolean): (ev: DesktopEvent) => void {
+  const paint = (code: string, s: string) => (color ? `\u001b[${code}m${s}\u001b[0m` : s)
+  return (ev) => {
+    if (ev.type === "log" && ev.text && ev.level !== "debug") console.log(paint("2", ev.text))
+    if (ev.type === "step") {
+      const mark = ev.ok ? paint("32", "✓") : paint("31", "✗")
+      const healed = ev.healed_target ? paint("33", " (healed)") : ""
+      const tries = ev.attempts && ev.attempts > 1 ? paint("33", ` (${ev.attempts} tries)`) : ""
+      const closed = ev.dismissed?.length ? paint("33", ` (closed ${ev.dismissed.join(", ")})`) : ""
+      const note = ev.note ? paint("2", `: ${ev.note}`) : ""
+      console.log(`${mark} ${String(ev.index).padStart(3)} ${ev.op}${healed}${tries}${closed}${ev.error ? `: ${ev.error}` : note}`)
+    }
+  }
+}
+
+export function abortOnSigint(): { signal: AbortSignal; done: () => void } {
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.once("SIGINT", onSigint)
+  return { signal: controller.signal, done: () => process.off("SIGINT", onSigint) }
+}
+
+export const color = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+
+function checkedConfig(flags: Flags, needsModel: boolean): AppConfig {
+  const cfg = loadConfig(configOpts(flags))
+  checkDesktopConfig(cfg, needsModel)
+  return cfg
+}
+
+export async function offerHeals(workflow: string, outDir: string, heals: NonNullable<DesktopResult["heals"]>, flags: Flags, signal: AbortSignal): Promise<void> {
+  if (!heals.length) return
+  const ask = boolFlag(flags, "accept-heals") ? undefined : terminalAsk(signal)
+  const accept =
+    boolFlag(flags, "accept-heals") ||
+    (ask
+      ? (await ask({
+          title: `${heals.length} step${heals.length === 1 ? "" : "s"} healed. Write the new locators into ${path.basename(workflow)}?`,
+          lines: heals.map((h) => `  step ${h.index}: ${JSON.stringify(h.old)} → ${JSON.stringify(h.new)}`),
+          options: [
+            { id: "no", label: "No, keep the workflow as it is (heals.json has them)" },
+            { id: "yes", label: "Yes, update the workflow" },
+          ],
+        })) === "yes"
+      : false)
+  if (accept) {
+    applyHeals(workflow, heals)
+    console.log(`updated ${workflow}`)
+  } else console.log(`heals   ${path.join(outDir, "heals.json")} (the workflow is unchanged; rerun with --accept-heals to write them)`)
+}
+
+/** The workflows the replay arguments name: .yaml files, and the desktop workflows directly inside a folder. */
+export function workflowFiles(paths: string[], cwd: string = process.cwd(), kind: "desktop" | "mobile" = "desktop"): string[] {
+  const format = new RegExp(`^format:\\s*["']?forgeqe-${kind}-v1["']?\\s*$`, "m")
+  const out: string[] = []
+  for (const p of paths) {
+    const full = path.resolve(cwd, p)
+    if (!existsSync(full)) throw new Error(`No workflow at ${full}`)
+    if (statSync(full).isDirectory()) {
+      const found = readdirSync(full)
+        .filter((f) => /\.ya?ml$/i.test(f))
+        .sort()
+        .map((f) => path.join(full, f))
+        .filter((f) => statSync(f).isFile() && format.test(readFileSync(f, "utf8")))
+      if (!found.length) throw new Error(`${full} has no ${kind} workflows (.yaml files with format: forgeqe-${kind}-v1)`)
+      out.push(...found)
+    } else if (/\.ya?ml$/i.test(full)) out.push(full)
+    else throw new Error(`${full} is not a workflow (.yaml or .yml) or a folder of them`)
+  }
+  return [...new Set(out)]
+}
+
+/** Replay words as workflow paths and name=value variables. */
+export function splitReplayArgs(words: string[]): { paths: string[]; variables: Record<string, string> } {
+  const vars = words.filter((w) => /^[A-Za-z_][A-Za-z0-9_]{0,63}=/.test(w))
+  return { paths: words.filter((w) => !vars.includes(w)), variables: parseVariables(vars) }
+}
+
+function caseDir(outDir: string, used: Set<string>, file: string): string {
+  const base = path.basename(file).replace(/\.ya?ml$/i, "").replace(/[^A-Za-z0-9_.-]/g, "_") || "workflow"
+  let name = base
+  for (let i = 2; used.has(name); i++) name = `${base}-${i}`
+  used.add(name)
+  return path.join(outDir, name)
+}
+
+async function cmdReplay(args: string[], flags: Flags): Promise<number> {
+  const { paths, variables } = splitReplayArgs(args)
+  if (!paths.length) throw new Error(DESKTOP_USAGE)
+  const workflows = workflowFiles(paths)
+  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 junit = strFlag(flags, "junit")
+  const cfg = checkedConfig(flags, false)
+  const healWanted = cfg.desktop.heal && !boolFlag(flags, "no-heal")
+  const updateBaselines = boolFlag(flags, "update-baselines")
+  if (healWanted && !hasModel(cfg)) console.error("Note: no model in llms.json, so moved controls will not be healed.")
+  await ensureDesktop((t) => console.error(t))
+  const outDir = desktopOutDir(cfg, "replay", strFlag(flags, "out"))
+  const { signal, done } = abortOnSigint()
+  const many = workflows.length > 1
+  try {
+    const results: { workflow: string; row: number; ok: boolean; report: string; error?: string }[] = []
+    const cases: JunitCase[] = []
+    const used = new Set<string>()
+    for (const workflow of workflows) {
+      const wfDir = many ? desktopOutDir(cfg, "replay", caseDir(outDir, used, workflow)) : outDir
+      const label = path.relative(process.cwd(), workflow) || workflow
+      if (many) console.log(`\n${label}`)
+      let offered = false
+      for (let i = 0; i < rows.length; i++) {
+        if (signal.aborted) break
+        const rowDir = rows.length > 1 ? desktopOutDir(cfg, "replay", path.join(wfDir, `row-${String(i + 1).padStart(3, "0")}`)) : wfDir
+        if (rows.length > 1) console.log(`\nrow ${i + 1} of ${rows.length}`)
+        const started = Date.now()
+        const run = await replayWorkflow({ cfg, workflow, variables: { ...variables, ...rows[i] }, heal: healWanted, updateBaselines, outDir: rowDir, signal, onEvent: printer(color()), log: (t) => console.error(t) })
+        const failed = (run.result.steps || []).find((s) => !s.ok)
+        const error = run.result.error || (failed ? `step ${failed.index} (${failed.op}): ${failed.error || "failed"}` : run.result.ok ? "" : "failed")
+        if (run.result.error) console.error(run.result.error)
+        console.log(`report  ${run.report}`)
+        results.push({ workflow: label, row: i + 1, ok: run.result.ok, report: run.report, ...(error ? { error } : {}) })
+        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 })
+        // Heals are offered once per workflow, from the first row that has them: every row runs the same steps.
+        if (run.result.heals?.length && !offered) {
+          offered = true
+          await offerHeals(workflow, rowDir, run.result.heals, flags, signal)
+        }
+      }
+    }
+    const planned = workflows.length * rows.length
+    if (planned > 1) {
+      writeFileSync(path.join(outDir, "runs.json"), JSON.stringify(results, null, 2))
+      const passed = results.filter((r) => r.ok).length
+      console.log(`\n${passed} of ${planned} runs passed${results.length < planned ? ` (${planned - results.length} not run)` : ""}  ${path.join(outDir, "runs.json")}`)
+    }
+    if (junit) {
+      const file = path.resolve(junit)
+      mkdirSync(path.dirname(file), { recursive: true })
+      writeFileSync(file, junitXml(cases))
+      console.log(`junit   ${file}`)
+    }
+    return results.length === planned && results.every((r) => r.ok) ? 0 : 1
+  } finally {
+    done()
+  }
+}
+
+/** `forgeqe desktop doctor`: whether replay can run here, unattended: the engine set up, and a session that takes input. */
+async function cmdDoctor(): Promise<number> {
+  const doc = desktopDoctor()
+  console.log(`engine   ${doc.ready ? `ready (${doc.python})` : `not ready (${doc.error}); run forgeqe desktop setup`}`)
+  console.log(`explore  ${doc.ufo ? `ready (UFO ${ufoCommit().slice(0, 12)})` : "not set up (forgeqe desktop setup --ufo)"}`)
+  if (!doc.ready) return 1
+  const r = spawnSync(doc.python, ["-m", "forgeqe_desktop", "doctor"], { env: engineEnv(), encoding: "utf8" })
+  let state: { session?: number; width?: number; height?: number; problem?: string | null } = {}
+  try {
+    state = JSON.parse((r.stdout || "").trim().split(/\r?\n/).pop() || "{}")
+  } catch {
+    state = { problem: (r.stderr || "the check did not run").trim().split(/\r?\n/).pop() }
+  }
+  console.log(`session  ${state.session ?? "?"}${state.width ? `, screen ${state.width}x${state.height}` : ""}`)
+  console.log(`desktop  ${state.problem ? `cannot be driven: ${state.problem}` : "logged in and unlocked"}`)
+  return state.problem ? 1 : 0
+}
+
+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(DESKTOP_USAGE)
+  const cfg = checkedConfig(flags, true)
+  checkApp(cfg, app)
+  const problem = visionProblem(cfg.activeProfile, cfg.llm)
+  if (problem) throw new Error(problem)
+  const { signal, done } = abortOnSigint()
+  try {
+    if (!boolFlag(flags, "yes")) {
+      const ask = terminalAsk(signal)
+      if (!ask) throw new Error("explore controls this desktop's mouse and keyboard; pass --yes to run it without a terminal to confirm in.")
+      const answer = await ask({
+        title: `UFO² will control this desktop's mouse and keyboard to: ${goal}`,
+        detail: `It starts ${app}, acts in its windows only (no shell commands), and its model is ${cfg.activeProfile}. Use a test machine and a test account.`,
+        options: [
+          { id: "no", label: "Cancel" },
+          { id: "yes", label: "Start" },
+        ],
+      })
+      if (answer !== "yes") return 1
+    }
+    const outDir = desktopOutDir(cfg, "explore", strFlag(flags, "out"))
+    const { result, report } = await exploreGoal({ cfg, goal, app, name: strFlag(flags, "name"), outDir, signal, onEvent: printer(color()), 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 desktop replay "${result.workflow}"`)
+    }
+    return result.ok ? 0 : 1
+  } finally {
+    done()
+  }
+}
+
+async function cmdRecord(flags: Flags): Promise<number> {
+  const app = strFlag(flags, "app")
+  if (!app) throw new Error(DESKTOP_USAGE)
+  const cfg = checkedConfig(flags, false)
+  checkApp(cfg, app)
+  const outDir = desktopOutDir(cfg, "record", strFlag(flags, "out"))
+  const { signal, done } = abortOnSigint()
+  try {
+    console.log(`Starting ${app}. Do the steps in it; Ctrl+Shift+F11 over a control adds a check of what it shows; Ctrl+Shift+F12 or closing the app stops.`)
+    const onEvent = (ev: DesktopEvent) => {
+      if (ev.type === "recorded") console.log(`${paintIf("36", "●")} ${String(ev.index).padStart(3)} ${ev.op}${ev.keys ? ` ${ev.keys}` : ""}${ev.target ? ` ${String(ev.target.name || ev.target.automation_id || "")}` : ""}`)
+      else printer(color())(ev)
+    }
+    const { result, report } = await recordByHand({ cfg, 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)`)
+      for (const s of result.skipped || []) console.log(`  not recorded: ${s.action}: ${s.reason}`)
+      for (const n of recordingNotes(cfg, result)) console.log(`note     ${n}`)
+      console.log(`replay   forgeqe desktop replay "${result.workflow}"`)
+    }
+    return result.ok ? 0 : 1
+  } finally {
+    done()
+  }
+}
+
+function paintIf(code: string, s: string): string {
+  return color() ? `\u001b[${code}m${s}\u001b[0m` : s
+}
+
+async function cmdValidate(args: string[]): Promise<number> {
+  const file = args[0]
+  if (!file) throw new Error(DESKTOP_USAGE)
+  // Any Python with PyYAML runs validate: the desktop engine's on Windows, else the browser engine's.
+  const desktop = desktopDoctor()
+  const python = desktop.ready ? desktop.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
+}
+
+function cmdApps(flags: Flags): number {
+  const cfg = loadConfig(configOpts(flags))
+  const apps = Object.entries(cfg.desktop.apps)
+  if (!apps.length) {
+    console.log("No apps in forgeqe.yaml desktop.apps. Add one:\n\ndesktop:\n  apps:\n    billing:\n      path: C:\\Program Files\\Contoso\\Billing\\Billing.exe\n      args: []\n  secrets: [BILLING_PASSWORD]")
+    return 0
+  }
+  for (const [name, raw] of apps) {
+    const r = (raw && typeof raw === "object" ? raw : {}) as { path?: unknown; args?: unknown }
+    console.log(`${name.padEnd(16)} ${String(r.path ?? "(no path)")}${Array.isArray(r.args) && r.args.length ? ` ${JSON.stringify(r.args)}` : ""}`)
+  }
+  console.log(`\nsecrets  ${cfg.desktop.secrets.join(", ") || "none"}`)
+  const own = privateDesktopSecrets(cfg)
+  if (own.length) console.log(`  ! ${own.join(", ")} ${own.length === 1 ? "is" : "are"} ForgeQE's own; remove from desktop.secrets`)
+  return 0
+}
+
+async function cmdSetup(flags: Flags): Promise<number> {
+  const python = await ensureDesktop((t) => console.log(t), { ufo: boolFlag(flags, "ufo"), force: boolFlag(flags, "force") })
+  const doc = desktopDoctor(python)
+  console.log(`python   ${python}`)
+  console.log(`replay   ${doc.ready ? "ready" : `not ready (${doc.error})`}`)
+  console.log(`explore  ${doc.ufo ? `ready (UFO ${ufoCommit().slice(0, 12)} in ${ufoDir()})` : "not set up (run forgeqe desktop setup --ufo)"}`)
+  return doc.ready ? 0 : 1
+}
+
+export async function cmdDesktop(args: string[], flags: Flags): Promise<number> {
+  const [sub, ...rest] = args
+  const windowsOnly = sub === "setup" || sub === "replay" || sub === "explore" || sub === "record" || sub === "doctor"
+  if (windowsOnly && process.platform !== "win32") {
+    console.error(NOT_WINDOWS)
+    return 2
+  }
+  switch (sub) {
+    case "setup":
+      return cmdSetup(flags)
+    case "apps":
+      return cmdApps(flags)
+    case "validate":
+      return cmdValidate(rest)
+    case "doctor":
+      return cmdDoctor()
+    case "replay":
+      return cmdReplay(rest, flags)
+    case "explore":
+      return cmdExplore(rest, flags)
+    case "record":
+      return cmdRecord(flags)
+    default:
+      console.log(DESKTOP_USAGE)
+      return sub ? 2 : 0
+  }
+}

package/src/desktop/edit.ts

@@ -0,0 +1,217 @@
+import { spawnSync } from "node:child_process"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+
+import YAML, { isMap, isSeq, type Document, type YAMLMap, type YAMLSeq } from "yaml"
+
+import { engineEnv, ensureEngine } from "../engine/setup.ts"
+import { lineDiff } from "../prompts.ts"
+import { desktopDoctor } from "./setup.ts"
+
+/**
+ * Changes to a desktop workflow that ForgeQE's agent proposes from chat (a longer timeout, a wait_for step, a dialog to
+ * dismiss, a healed locator), applied to the YAML with its comments and layout kept. Each change has a fixed shape and
+ * the result is checked by the engine's own validator before anything is written; the caller shows the diff and asks.
+ *
+ * Step numbers are the workflow's as it is now (the report's numbers), whatever earlier changes in the same call do.
+ */
+
+export const STEP_OPS = [
+  "launch", "click", "double_click", "type", "select", "keys", "expect", "expect_image", "wait", "wait_for", "close",
+  // mobile workflows (forgeqe-mobile-v1); the engine's validator checks each op belongs to the workflow's format
+  "tap", "double_tap", "long_press", "swipe", "scroll_to", "back", "hide_keyboard",
+] as const
+const TIMING_FIELDS = ["timeout", "retries"] as const
+const STEP_FIELDS = ["target", "text", "value", "keys", "seconds", "tolerance", "gone", "image", "ignore", "note", "timeout", "retries", "direction"] as const
+const VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/
+const MAX_CHANGES = 20
+
+export type WorkflowChange =
+  | { op: "set"; field: (typeof TIMING_FIELDS)[number]; value: number; step?: number }
+  | { op: "unset"; field: (typeof TIMING_FIELDS)[number]; step?: number }
+  | { op: "set_step"; step: number; field: (typeof STEP_FIELDS)[number]; value: unknown }
+  | { op: "add_dismiss"; target: Record<string, unknown> }
+  | { op: "insert_step"; before?: number; after?: number; step: Record<string, unknown> }
+  | { op: "remove_step"; step: number }
+  | { op: "set_variable"; name: string; value: string }
+
+export type WorkflowEdit = { before: string; after: string; diff: string[]; summary: string[] }
+
+/** The engine's validator: null when the text is a valid workflow, else why not. */
+export type ValidateWorkflow = (text: string) => Promise<string | null>
+
+const isObject = (v: unknown): v is Record<string, unknown> => Boolean(v) && typeof v === "object" && !Array.isArray(v)
+
+function stepNumber(v: unknown, count: number, what: string): number {
+  if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > count) throw new Error(`${what} must be a step number from 1 to ${count}`)
+  return v
+}
+
+/** The changes as given by the caller (the model): each checked against its shape; anything else is refused. */
+export function checkChanges(raw: unknown, count: number): WorkflowChange[] {
+  if (!Array.isArray(raw) || !raw.length) throw new Error("changes must be a non-empty list")
+  if (raw.length > MAX_CHANGES) throw new Error(`at most ${MAX_CHANGES} changes in one edit`)
+  return raw.map((c, i) => {
+    const where = `change ${i + 1}`
+    if (!isObject(c)) throw new Error(`${where} must be an object`)
+    const allow = (keys: string[]) => {
+      const extra = Object.keys(c).filter((k) => !keys.includes(k))
+      if (extra.length) throw new Error(`${where} (${String(c.op)}): unknown keys ${extra.join(", ")}`)
+    }
+    switch (c.op) {
+      case "set":
+      case "unset": {
+        allow(c.op === "set" ? ["op", "field", "value", "step"] : ["op", "field", "step"])
+        if (!TIMING_FIELDS.includes(c.field as never)) throw new Error(`${where}: field must be ${TIMING_FIELDS.join(" or ")}`)
+        if (c.op === "set" && (typeof c.value !== "number" || !Number.isFinite(c.value))) throw new Error(`${where}: value must be a number`)
+        const step = c.step === undefined ? undefined : stepNumber(c.step, count, `${where}: step`)
+        return { op: c.op, field: c.field, ...(c.op === "set" ? { value: c.value } : {}), ...(step ? { step } : {}) } as WorkflowChange
+      }
+      case "set_step":
+        allow(["op", "step", "field", "value"])
+        if (!STEP_FIELDS.includes(c.field as never)) throw new Error(`${where}: field must be one of ${STEP_FIELDS.join(", ")}`)
+        if (c.value === undefined) throw new Error(`${where}: value is required`)
+        return { op: "set_step", step: stepNumber(c.step, count, `${where}: step`), field: c.field, value: c.value } as WorkflowChange
+      case "add_dismiss":
+        allow(["op", "target"])
+        if (!isObject(c.target)) throw new Error(`${where}: target must be the dialog button's UIA properties`)
+        return { op: "add_dismiss", target: c.target }
+      case "insert_step": {
+        allow(["op", "before", "after", "step"])
+        if ((c.before === undefined) === (c.after === undefined)) throw new Error(`${where}: give before or after, a step number`)
+        if (!isObject(c.step) || !STEP_OPS.includes(c.step.op as never)) throw new Error(`${where}: step must be a workflow step with op one of ${STEP_OPS.join(", ")}`)
+        const at = c.before !== undefined ? { before: stepNumber(c.before, count, `${where}: before`) } : { after: stepNumber(c.after, count, `${where}: after`) }
+        return { op: "insert_step", ...at, step: c.step }
+      }
+      case "remove_step":
+        allow(["op", "step"])
+        return { op: "remove_step", step: stepNumber(c.step, count, `${where}: step`) }
+      case "set_variable":
+        allow(["op", "name", "value"])
+        if (typeof c.name !== "string" || !VAR_NAME.test(c.name)) throw new Error(`${where}: name must be letters, digits and _`)
+        if (typeof c.value !== "string" && typeof c.value !== "number") throw new Error(`${where}: value must be text`)
+        return { op: "set_variable", name: c.name, value: String(c.value) }
+      default:
+        throw new Error(`${where}: op must be set, unset, set_step, add_dismiss, insert_step, remove_step or set_variable`)
+    }
+  })
+}
+
+function describe(c: WorkflowChange): string {
+  switch (c.op) {
+    case "set":
+      return `${c.step ? `step ${c.step}` : "the workflow"}: ${c.field} ${c.value}`
+    case "unset":
+      return `${c.step ? `step ${c.step}` : "the workflow"}: no ${c.field}`
+    case "set_step":
+      return `step ${c.step}: ${c.field} = ${JSON.stringify(c.value)}`
+    case "add_dismiss":
+      return `dismiss ${JSON.stringify(c.target)} whenever it is in the way`
+    case "insert_step":
+      return `new ${String(c.step.op)} step ${c.before ? `before step ${c.before}` : `after step ${c.after}`}`
+    case "remove_step":
+      return `remove step ${c.step}`
+    case "set_variable":
+      return `variable ${c.name} = ${JSON.stringify(c.value)}`
+  }
+}
+
+/** Apply the changes to the workflow's text; comments and layout are kept. Throws on a change that cannot apply. */
+export function applyChanges(text: string, changes: WorkflowChange[]): string {
+  const doc: Document = YAML.parseDocument(text)
+  if (doc.errors.length) throw new Error(`the workflow is not valid YAML: ${doc.errors[0]!.message}`)
+  const steps = doc.get("steps", true)
+  if (!isSeq(steps)) throw new Error("the workflow has no steps list")
+  const seq = steps as YAMLSeq
+  const original = [...seq.items]
+  const at = (n: number): YAMLMap => {
+    const pos = seq.items.indexOf(original[n - 1]!)
+    if (pos < 0) throw new Error(`step ${n} was removed by an earlier change`)
+    const node = seq.items[pos]
+    if (!isMap(node)) throw new Error(`step ${n} is not a mapping`)
+    return node as YAMLMap
+  }
+  for (const c of changes) {
+    switch (c.op) {
+      case "set":
+        if (c.step) at(c.step).set(c.field, c.value)
+        else doc.set(c.field, c.value)
+        break
+      case "unset":
+        if (c.step) at(c.step).delete(c.field)
+        else doc.delete(c.field)
+        break
+      case "set_step":
+        at(c.step).set(c.field, doc.createNode(c.value, { flow: isObject(c.value) || Array.isArray(c.value) }))
+        break
+      case "add_dismiss": {
+        let list = doc.get("dismiss", true)
+        if (!isSeq(list)) {
+          doc.set("dismiss", doc.createNode([]))
+          list = doc.get("dismiss", true)
+        }
+        ;(list as YAMLSeq).add(doc.createNode(c.target, { flow: true }))
+        break
+      }
+      case "insert_step": {
+        const anchor = at((c.before ?? c.after)!)
+        const pos = seq.items.indexOf(anchor) + (c.after ? 1 : 0)
+        const node = doc.createNode(c.step) as YAMLMap
+        for (const pair of node.items) if (isMap(pair.value) || isSeq(pair.value)) pair.value.flow = true
+        seq.items.splice(pos, 0, node)
+        break
+      }
+      case "remove_step": {
+        const node = at(c.step)
+        seq.items.splice(seq.items.indexOf(node), 1)
+        break
+      }
+      case "set_variable": {
+        if (!isMap(doc.get("variables", true))) doc.set("variables", doc.createNode({}))
+        doc.setIn(["variables", c.name], c.value)
+        break
+      }
+    }
+  }
+  return doc.toString()
+}
+
+/** The proposed edit of `file`: before, after, diff and a line per change; checked by `validate`, nothing written. */
+export async function proposeEdit(file: string, rawChanges: unknown, validate: ValidateWorkflow): Promise<WorkflowEdit> {
+  const before = readFileSync(file, "utf8")
+  const parsed = YAML.parse(before) as { steps?: unknown[] } | null
+  const count = Array.isArray(parsed?.steps) ? parsed!.steps.length : 0
+  const changes = checkChanges(rawChanges, count)
+  const after = applyChanges(before, changes)
+  const problem = await validate(after)
+  if (problem) throw new Error(`The changed workflow would not run: ${problem}`)
+  return { before, after, diff: lineDiff(before.replace(/\n$/, ""), after.replace(/\n$/, "")), summary: changes.map(describe) }
+}
+
+/** Write an accepted edit, keeping the old text in `backupDir`; refuses when the file changed since it was proposed. */
+export function writeEdit(file: string, edit: WorkflowEdit, backupDir: string): string {
+  if (readFileSync(file, "utf8") !== edit.before) throw new Error(`${path.basename(file)} changed since the edit was proposed; propose it again.`)
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)
+  const backup = path.join(backupDir, `${stamp}-${path.basename(file)}`)
+  writeFileSync(backup, edit.before)
+  writeFileSync(file, edit.after)
+  return backup
+}
+
+/** The engine's own validator (`python -m forgeqe_desktop validate`), run on the text in a temporary file. */
+export const engineValidate: ValidateWorkflow = async (text) => {
+  const desktop = desktopDoctor()
+  const python = desktop.ready ? desktop.python : await ensureEngine(() => {})
+  const dir = mkdtempSync(path.join(tmpdir(), "fq-wf-"))
+  try {
+    const file = path.join(dir, "workflow.yaml")
+    writeFileSync(file, text)
+    const r = spawnSync(python, ["-m", "forgeqe_desktop", "validate", file], { env: engineEnv(), encoding: "utf8" })
+    if (r.error) throw r.error
+    if (r.status === 0) return null
+    return ((r.stderr || r.stdout || "").trim().split(/\r?\n/).pop() || "it is not a valid workflow").replace(/^error:\s*/, "")
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}

package/src/desktop/junit.ts

@@ -0,0 +1,35 @@
+/**
+ * JUnit XML for a desktop suite (`forgeqe desktop replay ... --junit FILE`), the format CI servers show as test
+ * results. Every value is escaped: step errors and control names come from the app under test.
+ */
+
+export type JunitCase = { suite: string; name: string; ok: boolean; seconds: number; error?: string; report?: string }
+
+/** `value` as XML text or attribute: markup escaped, and characters XML 1.0 cannot hold dropped. */
+export function xmlEscape(value: unknown): string {
+  return String(value ?? "")
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g, "")
+    .replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+}
+
+export function junitXml(cases: JunitCase[], name = "forgeqe desktop"): string {
+  const failures = cases.filter((c) => !c.ok).length
+  const seconds = cases.reduce((n, c) => n + c.seconds, 0)
+  const body = cases
+    .map((c) => {
+      const out = c.report ? `\n    <system-out>${xmlEscape(`report ${c.report}`)}</system-out>` : ""
+      const fail = c.ok ? "" : `\n    <failure message="${xmlEscape((c.error || "failed").split(/\r?\n/)[0]!.slice(0, 500))}">${xmlEscape(c.error || "failed")}</failure>`
+      return `  <testcase classname="${xmlEscape(c.suite)}" name="${xmlEscape(c.name)}" time="${c.seconds.toFixed(3)}">${fail}${out}\n  </testcase>`
+    })
+    .join("\n")
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuite name="${xmlEscape(name)}" tests="${cases.length}" failures="${failures}" errors="0" time="${seconds.toFixed(3)}">
+${body}
+</testsuite>
+`
+}