@capagents/forgeqe 1.3.2 → 2.0.1

package/src/environments.ts

@@ -0,0 +1,566 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import YAML from "yaml"
+
+import type { AppConfig, DesktopConfig, MobileConfig } from "./config.ts"
+
+/**
+ * Test environments (env.yaml, named in forgeqe.yaml `environments.file`): each has the apps a scenario can use (web,
+ * Windows desktop, mobile), plain variables, and the names of the secrets its apps' workflows may type. One is active
+ * (`--env`, FORGEQE_ENV, or the default); ForgeQE's agent picks the apps a request needs from it. No secret values
+ * belong in env.yaml: only the names of environment variables that hold them.
+ */
+
+export type AppKind = "web" | "desktop" | "mobile" | "api"
+
+export type TestApp = {
+  name: string
+  kind: AppKind
+  /** What the app is for, in the team's words: how the agent knows which app a step of a scenario belongs to. */
+  description?: string
+  /** web: where the app starts; api: the base URL its calls go to. */
+  url?: string
+  /** desktop: an absolute .exe, its arguments, and a main-window title pattern for launchers. */
+  path?: string
+  args?: string[]
+  window?: string
+  /** mobile: the platform and the app's package or bundle id; an Android activity, and an app file or upload to install. */
+  platform?: "android" | "ios"
+  appId?: string
+  activity?: string
+  appFile?: string
+  /** A saved login (logins: in forgeqe.yaml) the app signs in with. */
+  login?: string
+}
+
+export type Environment = {
+  name: string
+  description?: string
+  apps: Record<string, TestApp>
+  /** The web app browser runs start at when no URL is given (start_app; else the only web app). */
+  startApp?: string
+  /** The API app API tests call (api_app; else the only API app). */
+  apiApp?: string
+  /** Plain values a scenario may use (a company name, a test customer); never secrets. */
+  variables: Record<string, string>
+  /** Environment variables this environment's workflows may type with {{secret:NAME}}. */
+  secrets: string[]
+  /**
+   * The environment as the team wrote it, when env.yaml is in its own layout rather than ForgeQE's: YAML with every
+   * secret value replaced, for the agents to read the names and values the team uses (a db_server, a tenant id).
+   */
+  details?: string
+  /** Secret values written into the file itself: never used or shown, and reported so they can be moved out. */
+  literalSecrets?: string[]
+}
+
+export type EnvironmentsConfig = {
+  file: string
+  /** The environment ForgeQE uses unless a request names another. */
+  active?: string
+  all: Record<string, Environment>
+  /** desktop: from forgeqe.yaml alone, before an environment's apps are added (switching environments starts from it). */
+  baseDesktop: DesktopConfig
+  /** mobile: from forgeqe.yaml alone, likewise. */
+  baseMobile?: MobileConfig
+  /** browser.allowed_hosts, browser.start_url and api.base_url from forgeqe.yaml alone, likewise. */
+  baseHosts: string[]
+  baseStartUrl?: string
+  baseApiUrl?: string
+}
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/
+const VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/
+
+function record(value: unknown, where: string): Record<string, unknown> {
+  if (value === undefined || value === null) return {}
+  if (typeof value !== "object" || Array.isArray(value)) throw new Error(`${where} must be a mapping`)
+  return value as Record<string, unknown>
+}
+
+function text(value: unknown, where: string): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined
+  if (typeof value !== "string" && typeof value !== "number") throw new Error(`${where} must be text`)
+  return String(value)
+}
+
+function webUrl(raw: string, where: string): string {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    throw new Error(`${where} must be a full http(s) URL, e.g. https://qa.shop.example.com`)
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error(`${where} must be an http(s) URL, not ${url.protocol}`)
+  if (url.username || url.password) throw new Error(`${where} must not carry a user name or password; use logins: in forgeqe.yaml`)
+  return url.href
+}
+
+function parseApp(name: string, raw: unknown, where: string): TestApp {
+  if (!NAME.test(name)) throw new Error(`${where}: app names are letters, digits and _ . -`)
+  const r = record(raw, where)
+  const kind = String(r.kind || "")
+  if (kind !== "web" && kind !== "desktop" && kind !== "mobile" && kind !== "api") throw new Error(`${where}.kind must be web, desktop, mobile or api`)
+  const app: TestApp = { name, kind, ...(text(r.description, `${where}.description`) ? { description: text(r.description, `${where}.description`) } : {}) }
+  const login = text(r.login, `${where}.login`)
+  if (login) app.login = login
+  if (kind === "web" || kind === "api") {
+    const url = text(r.url, `${where}.url`)
+    if (!url) throw new Error(`${where}.url is required for a${kind === "api" ? "n api" : " web"} app`)
+    app.url = webUrl(url, `${where}.url`)
+  } else if (kind === "desktop") {
+    const p = text(r.path, `${where}.path`)
+    if (!p) throw new Error(`${where}.path is required for a desktop app (an absolute path to its .exe)`)
+    if (!/^([A-Za-z]:[\\/]|\\\\|\/)/.test(p) || !/\.exe$/i.test(p) || /[\x00-\x1f]/.test(p)) {
+      throw new Error(`${where}.path must be an absolute path to an .exe; .bat, .cmd and scripts run through a shell`)
+    }
+    app.path = p
+    const args = r.args ?? []
+    if (!Array.isArray(args) || !args.every((a) => typeof a === "string" || typeof a === "number")) {
+      throw new Error(`${where}.args must be a list of arguments, not one command string`)
+    }
+    app.args = args.map(String)
+    const window = text(r.window, `${where}.window`)
+    if (window) app.window = window
+  } else {
+    const platform = String(r.platform || "")
+    if (platform !== "android" && platform !== "ios") throw new Error(`${where}.platform must be android or ios`)
+    const appId = text(r.app_id ?? r.appId, `${where}.app_id`)
+    if (!appId || !/^[A-Za-z0-9_.-]+$/.test(appId)) throw new Error(`${where}.app_id must be the app's package or bundle id`)
+    app.platform = platform
+    app.appId = appId
+    const activity = text(r.activity, `${where}.activity`)
+    if (activity) {
+      if (platform !== "android" || !/^[A-Za-z0-9_.$]{1,200}$/.test(activity)) throw new Error(`${where}.activity must be an Android activity name such as .MainActivity`)
+      app.activity = activity
+    }
+    const file = text(r.app ?? r.app_file, `${where}.app`)
+    if (file) {
+      if (/[\x00-\x1f]/.test(file) || !(/^https:\/\//i.test(file) || /^(bs|lt):\/\/[A-Za-z0-9._-]+$/.test(file) || /^storage:filename=[A-Za-z0-9._-]+$/.test(file) || (path.isAbsolute(file) && /\.(apk|aab|ipa|app|zip)$/i.test(file)))) {
+        throw new Error(`${where}.app must be an absolute path to an .apk, .aab, .ipa, .app or .zip, an https URL, or a device cloud upload (bs://…)`)
+      }
+      app.appFile = file
+    }
+  }
+  return app
+}
+
+function parseEnvironment(name: string, raw: unknown): Environment {
+  const where = `env.yaml environments.${name}`
+  if (!NAME.test(name)) throw new Error(`${where}: environment names are letters, digits and _ . -`)
+  const r = record(raw, where)
+  const apps: Record<string, TestApp> = {}
+  for (const [appName, appRaw] of Object.entries(record(r.apps, `${where}.apps`))) apps[appName] = parseApp(appName, appRaw, `${where}.apps.${appName}`)
+  const variables: Record<string, string> = {}
+  for (const [k, v] of Object.entries(record(r.variables, `${where}.variables`))) {
+    if (!VAR_NAME.test(k)) throw new Error(`${where}.variables: "${k}" must be letters, digits and _`)
+    const value = text(v, `${where}.variables.${k}`)
+    variables[k] = value ?? ""
+  }
+  const secrets = r.secrets ?? []
+  if (!Array.isArray(secrets) || !secrets.every((s) => typeof s === "string" && VAR_NAME.test(s))) {
+    throw new Error(`${where}.secrets must be a list of environment variable names (letters, digits and _); env.yaml holds no secret values`)
+  }
+  const pick = (key: string, kind: AppKind): string | undefined => {
+    const named = text(r[key], `${where}.${key}`)
+    if (named) {
+      if (apps[named]?.kind !== kind) throw new Error(`${where}.${key} must name one of its ${kind} apps`)
+      return named
+    }
+    const ofKind = Object.values(apps).filter((a) => a.kind === kind)
+    return ofKind.length === 1 ? ofKind[0]!.name : undefined
+  }
+  const startApp = pick("start_app", "web")
+  const apiApp = pick("api_app", "api")
+  return {
+    name,
+    ...(text(r.description, `${where}.description`) ? { description: text(r.description, `${where}.description`) } : {}),
+    apps,
+    ...(startApp ? { startApp } : {}),
+    ...(apiApp ? { apiApp } : {}),
+    variables,
+    secrets: [...new Set(secrets as string[])],
+  }
+}
+
+
+/** Keys whose values are secrets, in any layout: never shown to a model, never used as values. */
+const SECRET_KEY = /(pass(word)?|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credential|conn(ection)?[_-]?str(ing)?|sas|cookie|auth)/i
+/** A secret written as a reference to an environment variable: ${NAME}, $NAME, env:NAME, %NAME%, {env:NAME}. */
+const SECRET_REF = /^\s*(?:\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)|env:([A-Za-z_][A-Za-z0-9_]*)|%([A-Za-z_][A-Za-z0-9_]*)%|\{env:([A-Za-z_][A-Za-z0-9_]*)\})\s*$/
+/** Inline credentials in a value: a connection string's Password=…, a URL's user:password@. */
+const INLINE_SECRET = /(password|pwd|secret|token|accountkey|sharedaccesskey)\s*=\s*[^;]+|\/\/[^/\s:@]+:[^/\s@]+@/i
+const URL_KEYS = /^(url|uri|base[_-]?url|baseurl|host|endpoint|address|link|base|site|web)$/i
+const PATH_KEYS = /^(path|exe|executable|program|binary|app[_-]?path)$/i
+const META_KEYS = new Set(["default", "default_env", "defaultenv", "default_environment", "defaultenvironment", "version", "common", "defaults", "shared", "global", "all"])
+
+const safeName = (s: string) => s.replace(/[^A-Za-z0-9_.-]+/g, "_").replace(/^[^A-Za-z0-9]+/, "").slice(0, 64)
+const safeVar = (s: string) => {
+  const v = s.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "")
+  return /^[A-Za-z_]/.test(v) ? v.slice(0, 64) : `v_${v}`.slice(0, 64)
+}
+
+function deepMerge(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...a }
+  for (const [k, v] of Object.entries(b)) {
+    const prev = out[k]
+    out[k] = prev && v && typeof prev === "object" && typeof v === "object" && !Array.isArray(prev) && !Array.isArray(v) ? deepMerge(prev as Record<string, unknown>, v as Record<string, unknown>) : v
+  }
+  return out
+}
+
+/** The mapping with every secret value replaced, for a model to read. */
+function redact(value: unknown, key = ""): unknown {
+  if (value && typeof value === "object" && !Array.isArray(value)) return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, redact(v, k)]))
+  if (Array.isArray(value)) return value.map((v) => redact(v, key))
+  if (typeof value === "string") {
+    if (SECRET_KEY.test(key)) return SECRET_REF.test(value) ? value.trim() : "<secret, not shown>"
+    if (INLINE_SECRET.test(value)) return value.replace(INLINE_SECRET, (m) => (m.startsWith("//") ? "//<user>:<secret>@" : `${m.split("=")[0]}=<secret>`))
+  }
+  return value
+}
+
+/** An environment in the team's own layout: apps, variables and secret names found wherever they are. */
+function parseFreeForm(name: string, r: Record<string, unknown>): Environment {
+  const apps: Record<string, TestApp> = {}
+  const variables: Record<string, string> = {}
+  const secrets = new Set<string>()
+  const literal: string[] = []
+  let primary: string | undefined
+  const addApp = (app: TestApp) => {
+    let n = safeName(app.name) || app.kind
+    for (let i = 2; apps[n]; i++) n = `${safeName(app.name) || app.kind}${i}`
+    apps[n] = { ...app, name: n }
+    return n
+  }
+  const walk = (node: unknown, trail: string[]) => {
+    if (node && typeof node === "object" && !Array.isArray(node)) {
+      const m = node as Record<string, unknown>
+      for (const [k, v] of Object.entries(m)) {
+        if (/^(description|desc)$/i.test(k) && trail.length === 0) continue
+        const at = [...trail, k]
+        if (typeof v === "string") {
+          const value = v.trim()
+          if (SECRET_KEY.test(k)) {
+            const ref = SECRET_REF.exec(value)
+            const refName = ref && (ref[1] || ref[2] || ref[3] || ref[4] || ref[5])
+            if (refName) secrets.add(refName)
+            else if (value) literal.push(at.join("."))
+            continue
+          }
+          if (INLINE_SECRET.test(value)) {
+            literal.push(at.join("."))
+            continue
+          }
+          // The app's name: the key, or for url/path-like keys the mapping it sits in.
+          const owner = (keys: RegExp, strip: RegExp) => (keys.test(k) ? trail[trail.length - 1] || "app" : k.replace(strip, "")) || k
+          if (/^https?:\/\//i.test(value)) {
+            try {
+              const url = webUrl(value, at.join("."))
+              const appName = owner(URL_KEYS, /[_-]?(base[_-]?)?(url|uri|endpoint|host)$/i)
+              const kind: AppKind = /api/i.test(at.join(".")) || /\/api(\/|$)/i.test(new URL(url).pathname) ? "api" : "web"
+              const desc = typeof m.description === "string" ? m.description : undefined
+              const added = addApp({ name: appName, kind, url, ...(URL_KEYS.test(k) && desc ? { description: desc } : {}) })
+              // A URL at the environment's top level (base_url, url) is its main web app: where browser runs start.
+              if (trail.length === 0 && URL_KEYS.test(k) && kind === "web" && !primary) primary = added
+            } catch {
+              // A URL with credentials or another scheme is not an app: it stays out of what the agents can open.
+            }
+            continue
+          }
+          if (/^([A-Za-z]:[\\/]|\\\\|\/).*\.exe$/i.test(value) && !/[\x00-\x1f]/.test(value)) {
+            const args = Array.isArray(m.args) ? m.args : Array.isArray(m.arguments) ? m.arguments : []
+            addApp({ name: owner(PATH_KEYS, /[_-]?(path|exe)$/i), kind: "desktop", path: value, args: args.filter((a) => typeof a === "string" || typeof a === "number").map(String), ...(typeof m.description === "string" ? { description: m.description } : {}) })
+            continue
+          }
+          if (value.length <= 500 && !/[\r\n]/.test(value)) variables[safeVar(at.join("_"))] = value
+        } else if (typeof v === "number" || typeof v === "boolean") {
+          if (!SECRET_KEY.test(k)) variables[safeVar(at.join("_"))] = String(v)
+        } else if (Array.isArray(v)) {
+          if (/^(args|arguments)$/i.test(k)) continue
+          if (/^secrets?$/i.test(k)) {
+            for (const s of v) {
+              if (typeof s !== "string" || !VAR_NAME.test(s)) throw new Error(`env.yaml ${name}: ${[...at].join(".")} must be a list of environment variable names (letters, digits and _); env.yaml holds no secret values`)
+              secrets.add(s)
+            }
+            continue
+          }
+          if (!SECRET_KEY.test(k) && v.every((x) => typeof x === "string" || typeof x === "number") && v.length <= 50) variables[safeVar(at.join("_"))] = v.join(", ")
+        } else if (v && typeof v === "object") walk(v, at)
+      }
+    }
+  }
+  walk(r, [])
+  const details = YAML.stringify(redact(r)).trim()
+  const env: Environment = {
+    name,
+    ...(typeof r.description === "string" ? { description: r.description } : {}),
+    apps,
+    variables,
+    secrets: [...secrets],
+    details: details.length > 6000 ? `${details.slice(0, 6000)}\n# …` : details,
+    ...(literal.length ? { literalSecrets: literal } : {}),
+  }
+  const web = Object.values(apps).filter((a) => a.kind === "web")
+  const api = Object.values(apps).filter((a) => a.kind === "api")
+  if (primary) env.startApp = primary
+  else if (web.length === 1) env.startApp = web[0]!.name
+  if (api.length === 1) env.apiApp = api[0]!.name
+  return env
+}
+
+/** ForgeQE's own layout: apps with a kind each (env.example.yaml). */
+function isForgeqeLayout(r: Record<string, unknown>): boolean {
+  const apps = r.apps
+  return Boolean(apps && typeof apps === "object" && !Array.isArray(apps) && Object.values(apps).length && Object.values(apps).every((a) => a && typeof a === "object" && "kind" in (a as object)))
+}
+
+function anyEnvironment(name: string, raw: unknown, common: Record<string, unknown>): Environment {
+  if (!NAME.test(name)) throw new Error(`env.yaml: "${name}": environment names are letters, digits and _ . -`)
+  const r = deepMerge(common, record(raw, `env.yaml ${name}`))
+  return isForgeqeLayout(r) ? parseEnvironment(name, r) : parseFreeForm(name, r)
+}
+
+/**
+ * The environments in a document of any layout: `environments:` (or `envs:`), else every top-level mapping that is
+ * not a setting (default, common, …). A `common` / `defaults` / `shared` block is merged into each.
+ */
+function environmentsOf(doc: Record<string, unknown>): Record<string, Environment> {
+  // A list of environments, each with its name: [{ name: qa, url: … }, …].
+  const list = [doc.environments, doc.envs].find((c) => Array.isArray(c)) as unknown[] | undefined
+  if (list) {
+    const out: Record<string, Environment> = {}
+    for (const item of list) {
+      const r = record(item, "env.yaml environments[]")
+      const name = String(r.name ?? r.env ?? r.id ?? "")
+      if (!name) throw new Error("env.yaml: each environment in the list needs a name")
+      const { name: _n, env: _e, id: _i, ...rest } = r
+      out[name] = anyEnvironment(name, rest, {})
+    }
+    return out
+  }
+  const container = [doc.environments, doc.envs, doc.environment].find((c) => c && typeof c === "object" && !Array.isArray(c)) as Record<string, unknown> | undefined
+  const from = container || doc
+  const commonRaw = [from.common, from.defaults, from.shared, from.global, doc.common, doc.defaults, doc.shared].find((c) => c && typeof c === "object" && !Array.isArray(c)) as Record<string, unknown> | undefined
+  const all: Record<string, Environment> = {}
+  for (const [name, raw] of Object.entries(from)) {
+    if (META_KEYS.has(name.toLowerCase()) || !raw || typeof raw !== "object" || Array.isArray(raw)) continue
+    if (!container && ["environments", "envs", "environment"].includes(name)) continue
+    all[name] = anyEnvironment(name, raw, commonRaw || {})
+  }
+  return all
+}
+
+const defaultOf = (doc: Record<string, unknown>) =>
+  [doc.default, doc.default_env, doc.defaultEnv, doc.default_environment, doc.defaultEnvironment].find((v) => typeof v === "string" && v) as string | undefined
+
+/** env.yaml's environments, and which is active: `requested` (--env, FORGEQE_ENV), else forgeqe.yaml's default, else env.yaml's. */
+export function loadEnvironments(
+  settings: Record<string, unknown>,
+  base: string,
+  baseDesktop: DesktopConfig,
+  requested?: string,
+  baseHosts: string[] = [],
+  base2: { startUrl?: string; apiUrl?: string; mobile?: MobileConfig } = {},
+): EnvironmentsConfig | undefined {
+  const fileSetting = settings.file === undefined ? undefined : String(settings.file || "")
+  const dirSetting = settings.dir === undefined ? undefined : String(settings.dir || "")
+  if (fileSetting === undefined && dirSetting === undefined && !requested) return undefined
+  let file: string
+  let all: Record<string, Environment> = {}
+  let docDefault: string | undefined
+  if (dirSetting !== undefined) {
+    // One file per environment (qa.yaml, uat.yaml): the file's name is the environment's.
+    file = path.resolve(base, dirSetting || ".")
+    if (!existsSync(file)) throw new Error(`environments.dir in forgeqe.yaml names ${file}, which does not exist.`)
+    for (const f of readdirSync(file).filter((n) => /\.(ya?ml|json)$/i.test(n)).sort()) {
+      const doc = YAML.parse(readFileSync(path.join(file, f), "utf8")) ?? {}
+      all[f.replace(/\.(ya?ml|json)$/i, "")] = anyEnvironment(f.replace(/\.(ya?ml|json)$/i, ""), doc, {})
+    }
+  } else {
+    file = path.resolve(base, fileSetting || "./env.yaml")
+    if (!existsSync(file)) {
+      if (fileSetting === undefined) throw new Error(`--env ${requested}: there is no env.yaml here. Add environments: { file: ./env.yaml } to forgeqe.yaml.`)
+      throw new Error(`environments.file in forgeqe.yaml names ${file}, which does not exist. Run forgeqe init to create one.`)
+    }
+    const doc = record(YAML.parse(readFileSync(file, "utf8")) ?? {}, "env.yaml")
+    all = environmentsOf(doc)
+    docDefault = defaultOf(doc)
+  }
+  const names = Object.keys(all)
+  const fallback = text(settings.default, "environments.default") || docDefault || (names.length === 1 ? names[0] : undefined)
+  const active = requested || fallback
+  if (active && !all[active]) throw new Error(`No environment "${active}" in ${file} (environments: ${names.join(", ") || "none"}).`)
+  return { file, ...(active ? { active } : {}), all, baseDesktop, ...(base2.mobile ? { baseMobile: base2.mobile } : {}), baseHosts, ...(base2.startUrl ? { baseStartUrl: base2.startUrl } : {}), ...(base2.apiUrl ? { baseApiUrl: base2.apiUrl } : {}) }
+}
+
+/** The desktop apps of an environment, in the form desktop.apps takes (the engine checks each entry again). */
+function desktopApps(env: Environment): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const app of Object.values(env.apps)) {
+    if (app.kind === "desktop") out[app.name] = { path: app.path, args: app.args || [], ...(app.window ? { window: app.window } : {}) }
+  }
+  return out
+}
+
+/** The mobile apps of an environment, in the form mobile.apps takes (the engine checks each entry again). */
+function mobileApps(env: Environment): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const app of Object.values(env.apps)) {
+    if (app.kind === "mobile") out[app.name] = { platform: app.platform, app_id: app.appId, ...(app.activity ? { activity: app.activity } : {}), ...(app.appFile ? { app: app.appFile } : {}) }
+  }
+  return out
+}
+
+/**
+ * The config with `name`'s apps and secrets in effect: its desktop apps join desktop.apps (an environment's entry wins
+ * over forgeqe.yaml's of the same name), its mobile apps join mobile.apps, and its secrets join desktop.secrets and
+ * mobile.secrets. The config is not changed.
+ */
+export function withEnvironment(cfg: AppConfig, name?: string): AppConfig {
+  const envs = cfg.environments
+  if (!envs) {
+    if (name) throw new Error(`No environments are configured, so "${name}" cannot be used. Add environments: { file: ./env.yaml } to forgeqe.yaml.`)
+    return cfg
+  }
+  const chosen = name || envs.active
+  if (!chosen) return cfg
+  const env = envs.all[chosen]
+  if (!env) throw new Error(`No environment "${chosen}" in ${envs.file} (environments: ${Object.keys(envs.all).join(", ") || "none"}).`)
+  const base = envs.baseDesktop
+  // An allow-list of hosts (browser.allowed_hosts) also lets in this environment's web apps; an empty one allows any.
+  const webHosts = Object.values(env.apps).flatMap((a) => ((a.kind === "web" || a.kind === "api") && a.url ? [new URL(a.url).hostname] : []))
+  const hosts = envs.baseHosts.length ? [...new Set([...envs.baseHosts, ...webHosts])] : envs.baseHosts
+  // The environment's start app and API app win over forgeqe.yaml's start_url and api.base_url: they are what differs
+  // between environments. Without them, forgeqe.yaml's stay.
+  const startUrl = env.startApp ? env.apps[env.startApp]!.url : envs.baseStartUrl
+  const apiUrl = env.apiApp ? env.apps[env.apiApp]!.url : envs.baseApiUrl
+  return {
+    ...cfg,
+    browser: { ...cfg.browser, allowedHosts: hosts, startUrl },
+    ...(cfg.api ? { api: { ...cfg.api, baseUrl: apiUrl } } : {}),
+    environments: { ...envs, active: chosen },
+    desktop: { ...base, apps: { ...base.apps, ...desktopApps(env) }, secrets: [...new Set([...base.secrets, ...env.secrets])] },
+    ...(envs.baseMobile
+      ? { mobile: { ...envs.baseMobile, apps: { ...envs.baseMobile.apps, ...mobileApps(env) }, secrets: [...new Set([...envs.baseMobile.secrets, ...env.secrets])] } }
+      : {}),
+  }
+}
+
+export function activeEnvironment(cfg: AppConfig): Environment | undefined {
+  const envs = cfg.environments
+  return envs?.active ? envs.all[envs.active] : undefined
+}
+
+/** A web app's URL in the active (or named) environment; throws for an unknown app or one that is not a web app. */
+export function webAppUrl(cfg: AppConfig, app: string, env?: string): string {
+  const c = withEnvironment(cfg, env)
+  const e = activeEnvironment(c)
+  const found = e?.apps[app]
+  if (!found) throw new Error(`No app "${app}" in ${e ? `environment ${e.name}` : "env.yaml (no environment is active)"}${e ? ` (apps: ${Object.keys(e.apps).join(", ") || "none"})` : ""}.`)
+  if (found.kind !== "web" || !found.url) throw new Error(`App "${app}" is a ${found.kind} app, not a web app: use the ${found.kind} tools for it.`)
+  return found.url
+}
+
+/** An app name as part of an environment variable name: SHOP for shop, ORDER_API for order-api. */
+const envKey = (name: string) => name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")
+
+/**
+ * What tests and other programs ForgeQE runs read the environment from: FORGEQE_ACTIVE_ENV, FORGEQE_APP_<APP>_URL (web
+ * and API apps), FORGEQE_APP_<APP>_PATH (desktop apps), FORGEQE_VAR_<NAME> (variables). Never secrets: those stay in
+ * the variables env.yaml names.
+ */
+export function environmentVariables(cfg: AppConfig): Record<string, string> {
+  const env = activeEnvironment(cfg)
+  if (!env) return {}
+  const out: Record<string, string> = { FORGEQE_ACTIVE_ENV: env.name }
+  for (const a of Object.values(env.apps)) {
+    if (a.url) out[`FORGEQE_APP_${envKey(a.name)}_URL`] = a.url
+    if (a.path) out[`FORGEQE_APP_${envKey(a.name)}_PATH`] = a.path
+    if (a.appId) out[`FORGEQE_APP_${envKey(a.name)}_ID`] = a.appId
+  }
+  for (const [k, v] of Object.entries(env.variables)) out[`FORGEQE_VAR_${envKey(k)}`] = v
+  // A line break would let a value set another variable where these are written line by line (CI env files).
+  for (const [k, v] of Object.entries(out)) if (/[\r\n]/.test(v)) delete out[k]
+  return out
+}
+
+const EXPORTED = /^FORGEQE_(ACTIVE_ENV$|APP_|VAR_)/
+
+/** Put the active environment's variables into this process's environment, so every test command and agent sees them. */
+export function exportEnvironment(cfg: AppConfig, env: Record<string, string | undefined> = process.env): void {
+  for (const k of Object.keys(env)) if (EXPORTED.test(k)) delete env[k]
+  Object.assign(env, environmentVariables(cfg))
+}
+
+/**
+ * The environment as one agent needs it. agent: ForgeQE's agent, which picks apps for requests and scenarios. browser:
+ * the browser agent, which must stay on this environment's hosts. code: Scribe, the healer and the reviewer, which
+ * write and fix tests that must run in every environment.
+ */
+export function environmentBrief(cfg: AppConfig, audience: "agent" | "browser" | "code"): string {
+  const env = activeEnvironment(cfg)
+  if (!env) return ""
+  const apps = Object.values(env.apps)
+  const appLine = (a: TestApp) => {
+    const where = a.url || a.path || (a.appId ? `${a.platform} ${a.appId}` : "")
+    return `- ${a.name} (${a.kind}${where ? `: ${where}` : ""})${a.description ? `: ${a.description}` : ""}`
+  }
+  const values = Object.entries(env.variables)
+  if (audience === "browser") {
+    const web = apps.filter((a) => a.kind === "web" || a.kind === "api")
+    if (!web.length && !values.length) return ""
+    return [
+      `Test environment: ${env.name}${env.description ? ` (${env.description})` : ""}.`,
+      ...(web.length ? ["Its web apps, where a goal that names one of them means:", ...web.map(appLine), "Stay on this environment's hosts; never use another environment's URL for these apps."] : []),
+      ...(values.length ? ["Values of this environment, for goals that refer to them:", ...values.map(([k, v]) => `- ${k}: ${v}`)] : []),
+    ].join("\n")
+  }
+  if (audience === "code") {
+    const vars = environmentVariables(cfg)
+    const urls = Object.entries(vars).filter(([k]) => /_URL$/.test(k))
+    return [
+      `The tests run against test environment ${env.name}; others are ${Object.keys(cfg.environments!.all).filter((n) => n !== env.name).join(", ") || "none yet"}. A test must run unchanged in every environment:`,
+      "- Never write an environment's URL, host or app path into a test. Read it where the repository already keeps its base URL or settings; if it keeps none, read these variables, which ForgeQE sets whenever it runs the tests, with the repository's own default as fallback:",
+      ...urls.map(([k, v]) => `  ${k} (now ${v})`),
+      "- FORGEQE_ACTIVE_ENV names the environment, and FORGEQE_VAR_<NAME> holds its values (" + (values.map(([k]) => k).join(", ") || "none") + "). Secrets are never in these variables.",
+    ].join("\n")
+  }
+  const others = Object.values(cfg.environments!.all).filter((e) => e.name !== env.name)
+  return [
+    `Test environment in use: ${env.name}${env.description ? ` (${env.description})` : ""}, from ${cfg.environments!.file}.${others.length ? ` Others: ${others.map((e) => e.name).join(", ")} (use_environment switches; tools also take env for one call).` : ""}`,
+    apps.length ? ["Its apps (pick by description; never invent a URL or path):", ...apps.map(appLine)].join("\n") : "It has no apps yet.",
+    env.details
+      ? `The environment as the team wrote it (secrets replaced); use its names and values when a request refers to them:\n\`\`\`yaml\n${env.details}\n\`\`\``
+      : values.length
+        ? `Its values: ${values.map(([k, v]) => `${k}=${v}`).join(", ")}.`
+        : "",
+    env.secrets.length ? `Secrets its workflows may use, by name only: ${env.secrets.join(", ")}.` : "",
+    env.literalSecrets?.length ? `Secret values are written in the file at ${env.literalSecrets.join(", ")}: they are not used or shown; tell the user to move them to environment variables.` : "",
+    env.startApp ? `Browser runs start at ${env.startApp} when no app or URL is given.` : "",
+  ]
+    .filter(Boolean)
+    .join("\n")
+}
+
+/** `forgeqe apps`: the environments, and the apps of the active (or named) one. */
+export function appsText(cfg: AppConfig, env?: string): string {
+  if (!cfg.environments) return "No environments are configured. Run forgeqe init (it writes env.yaml), or add environments: { file: ./env.yaml } to forgeqe.yaml."
+  const c = withEnvironment(cfg, env)
+  const active = activeEnvironment(c)
+  const lines: string[] = [`environments  (${c.environments!.file})`]
+  for (const e of Object.values(c.environments!.all)) lines.push(`${e.name === active?.name ? "*" : " "} ${e.name.padEnd(12)} ${e.description || ""}`.trimEnd())
+  if (!active) return [...lines, "", "No environment is active: pass --env NAME, set FORGEQE_ENV, or set default in env.yaml."].join("\n")
+  lines.push("", `apps in ${active.name}`)
+  for (const a of Object.values(active.apps)) {
+    const where = a.url ? a.url : a.path ? `${a.path}${a.args?.length ? ` ${JSON.stringify(a.args)}` : ""}` : `${a.platform} ${a.appId}`
+    lines.push(`  ${a.name.padEnd(14)} ${a.kind.padEnd(8)} ${where}${a.description ? `\n  ${"".padEnd(14)} ${"".padEnd(8)} ${a.description}` : ""}`)
+  }
+  if (!Object.keys(active.apps).length) lines.push("  (none)")
+  const vars = Object.entries(active.variables)
+  if (vars.length) lines.push("", "variables", ...vars.map(([k, v]) => `  ${k} = ${v}`))
+  if (active.literalSecrets?.length) lines.push("", `! secret values written in the file (not used; move them to environment variables): ${active.literalSecrets.join(", ")}`)
+  lines.push("", `secrets  ${c.desktop.secrets.join(", ") || "none"}`)
+  return lines.join("\n")
+}

package/src/evals/domain.ts

@@ -238,6 +238,7 @@ export async function runDomainEval(opts: EvalOptions): Promise<EvalReport> {
             profile: judgeConfig.llm,
             // The judge is given the domain as data and must not apply the domain rule itself.
             domain: null,
+            guardrails: null,
             role: "judge",
             model: judgeConfig.code.model,
             bin: judgeConfig.code.opencode,

package/src/explore/charters.ts

@@ -6,6 +6,7 @@ import type { Story } from "./story.ts"
 import { domainNotes } from "../domain.ts"
 import { knowledgeBlock, readKnowledge, relevantKnowledge } from "../knowledge.ts"
 import { prompt } from "../prompts.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 /**
  * Exploratory charters: what to try on a story's feature beyond its scripted test cases. Each charter has a mission (the
@@ -113,6 +114,7 @@ export async function planCharters(opts: {
     repo: opts.cwd,
     profile: opts.config.llm,
     domain: domainNotes(opts.config),
+    guardrails: guardrailsNotes(opts.config),
     model: opts.config.code.model,
     bin: opts.config.code.opencode,
     readDirs: [opts.cwd],