@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/memory.ts

@@ -0,0 +1,250 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs"
+import path from "node:path"
+
+/** Readers for the engine's page memory (pages/<host>/*.json, flows/*.json) behind `forgeqe memory` and /memory. */
+
+export type MemoryLocator = {
+  type: string
+  value: string
+  playwright: string
+  confidence: number
+  seen?: number
+  missed?: number
+  success?: number
+  failure?: number
+}
+
+export type MemoryElement = {
+  key: string
+  tag: string
+  role?: string | null
+  name?: string | null
+  text?: string | null
+  attributes?: Record<string, string>
+  locators: MemoryLocator[]
+  best?: string | null
+  confidence: number
+  visits?: number
+  interactions?: number
+  success?: number
+  failure?: number
+  first_seen?: string
+  last_seen?: string
+  last_used?: string
+  last_updated?: string
+}
+
+export type MemoryPage = {
+  host: string
+  path: string
+  title?: string
+  visits?: number
+  first_seen?: string
+  last_seen?: string
+  sample_urls?: string[]
+  elements: Record<string, MemoryElement>
+  file: string
+}
+
+export type MemoryFlow = {
+  goal: string
+  start_url?: string
+  host?: string
+  runs?: number
+  successes?: number
+  failures?: number
+  replays?: number
+  llm_steps?: number
+  replayed_steps?: number
+  last_success?: string
+  last_run?: string
+  last_status?: string
+  steps: { action: string; line?: string }[]
+  file: string
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as T
+  } catch {
+    return null
+  }
+}
+
+function jsonFiles(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => path.join(dir, f))
+}
+
+export function readPages(dir: string): MemoryPage[] {
+  const root = path.join(dir, "pages")
+  if (!existsSync(root)) return []
+  const pages: MemoryPage[] = []
+  for (const host of readdirSync(root)) {
+    for (const file of jsonFiles(path.join(root, host))) {
+      const page = readJson<Omit<MemoryPage, "file">>(file)
+      if (page && page.host && page.elements) pages.push({ ...page, file })
+    }
+  }
+  return pages
+}
+
+export function readFlows(dir: string): MemoryFlow[] {
+  const flows: MemoryFlow[] = []
+  for (const file of jsonFiles(path.join(dir, "flows"))) {
+    const flow = readJson<Omit<MemoryFlow, "file">>(file)
+    if (flow && flow.goal && Array.isArray(flow.steps)) flows.push({ ...flow, file })
+  }
+  return flows.sort((a, b) => String(b.last_run || "").localeCompare(String(a.last_run || "")))
+}
+
+const when = (iso?: string) => (iso ? iso.slice(0, 16).replace("T", " ") : "—")
+const clip = (s: string, n: number) => (s.length <= n ? s : `${s.slice(0, n - 1)}…`)
+
+function table(rows: string[][], right: number[] = []): string[] {
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => r[i].length)))
+  return rows.map((r) =>
+    r
+      .map((cell, i) => (i === r.length - 1 ? cell : right.includes(i) ? cell.padStart(widths[i]) : cell.padEnd(widths[i])))
+      .join("  ")
+      .trimEnd(),
+  )
+}
+
+function hostMatches(host: string, target: string): boolean {
+  const h = host.toLowerCase()
+  const t = target.toLowerCase().replace(/^www\./, "")
+  return h === t || h === `www.${t}` || h.endsWith(`.${t}`)
+}
+
+function pathPattern(template: string): RegExp {
+  const escaped = template.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]+")
+  return new RegExp(`^${escaped}$`)
+}
+
+/** The page file for a URL: same host (and port), and a path that fits the stored template. */
+export function findPage(pages: MemoryPage[], url: string): MemoryPage | undefined {
+  let u: URL
+  try {
+    u = new URL(url.includes("://") ? url : `https://${url}`)
+  } catch {
+    return undefined
+  }
+  const host = u.port ? `${u.hostname}:${u.port}` : u.hostname
+  const route = u.hash.startsWith("#/") || u.hash.startsWith("#!/") ? u.hash.split("?")[0] : ""
+  const target = (u.pathname.replace(/\/+$/, "") || "/") + route
+  const candidates = pages.filter((p) => p.host === host || hostMatches(p.host, u.hostname))
+  return candidates.find((p) => p.path === target) || candidates.find((p) => pathPattern(p.path).test(target))
+}
+
+export function memoryOverview(dir: string): string {
+  const pages = readPages(dir)
+  const flows = readFlows(dir)
+  if (!pages.length && !flows.length) return `No page memory yet in ${dir}\nIt fills up as live runs visit pages.`
+  const hosts = new Map<string, { pages: number; elements: number; flows: number; last: string }>()
+  for (const p of pages) {
+    const h = hosts.get(p.host) || { pages: 0, elements: 0, flows: 0, last: "" }
+    h.pages++
+    h.elements += Object.keys(p.elements).length
+    if ((p.last_seen || "") > h.last) h.last = p.last_seen || ""
+    hosts.set(p.host, h)
+  }
+  for (const f of flows) {
+    const h = hosts.get(f.host || "?") || { pages: 0, elements: 0, flows: 0, last: "" }
+    h.flows++
+    hosts.set(f.host || "?", h)
+  }
+  const rows = [["HOST", "PAGES", "ELEMENTS", "FLOWS", "LAST SEEN"]]
+  for (const [host, h] of [...hosts].sort((a, b) => b[1].last.localeCompare(a[1].last))) {
+    rows.push([host, String(h.pages), String(h.elements), String(h.flows), when(h.last)])
+  }
+  return [`Memory  ${dir}`, "", ...table(rows, [1, 2, 3]), "", "forgeqe memory show <host|url>   ·   forgeqe memory flows"].join("\n")
+}
+
+function elementLabel(e: MemoryElement): string {
+  const label = e.name || e.text || e.attributes?.placeholder || e.attributes?.["aria-label"] || ""
+  return label ? `${e.tag} "${clip(label, 36)}"` : e.tag
+}
+
+function pageDetail(page: MemoryPage, opts: { locators: boolean; limit: number }): string {
+  const elements = Object.values(page.elements).sort(
+    (a, b) => (b.interactions || 0) - (a.interactions || 0) || b.confidence - a.confidence,
+  )
+  const shown = opts.limit > 0 ? elements.slice(0, opts.limit) : elements
+  const lines = [
+    `${page.host}${page.path}  ${page.title || ""}`.trimEnd(),
+    `${page.visits || 0} visits · ${elements.length} elements · first seen ${when(page.first_seen)} · last seen ${when(page.last_seen)}`,
+    "",
+  ]
+  const rows = [["CONF", "ELEMENT", "USED", "LAST SEEN", "BEST LOCATOR"]]
+  for (const e of shown) {
+    const used = e.interactions ? `${e.interactions}× ${e.failure ? `${e.failure} failed` : "ok"}` : "—"
+    rows.push([`${e.confidence}%`, elementLabel(e), used, when(e.last_seen), e.best || "—"])
+  }
+  const body = table(rows, [0])
+  if (!opts.locators) {
+    lines.push(...body)
+  } else {
+    lines.push(body[0])
+    shown.forEach((e, i) => {
+      lines.push(body[i + 1])
+      for (const l of e.locators) {
+        const evidence = `seen ${l.seen || 0}${l.missed ? `, missed ${l.missed}` : ""}${l.success ? `, ok ${l.success}` : ""}${l.failure ? `, failed ${l.failure}` : ""}`
+        lines.push(`        ${String(l.confidence).padStart(2)}%  ${l.type.padEnd(11)} ${l.playwright}   (${evidence})`)
+      }
+    })
+  }
+  if (shown.length < elements.length) lines.push("", `${elements.length - shown.length} more; pass --all to list every element.`)
+  return lines.join("\n")
+}
+
+export function memoryShow(dir: string, target: string, opts: { locators?: boolean; limit?: number } = {}): string {
+  const pages = readPages(dir)
+  const detail = { locators: Boolean(opts.locators), limit: opts.limit ?? 40 }
+  const looksLikeUrl = target.includes("://") || target.includes("/")
+  if (looksLikeUrl) {
+    const page = findPage(pages, target)
+    return page ? pageDetail(page, detail) : `No memory for ${target} yet.`
+  }
+  const onHost = pages.filter((p) => hostMatches(p.host, target))
+  if (!onHost.length) return `No memory for ${target} yet.`
+  if (onHost.length === 1) return pageDetail(onHost[0], detail)
+  const rows = [["PATH", "VISITS", "ELEMENTS", "LAST SEEN", "TITLE"]]
+  for (const p of onHost.sort((a, b) => (b.visits || 0) - (a.visits || 0))) {
+    rows.push([p.path, String(p.visits || 0), String(Object.keys(p.elements).length), when(p.last_seen), clip(p.title || "", 50)])
+  }
+  const host = onHost[0].host
+  return [`${host}  (${onHost.length} pages)`, "", ...table(rows, [1, 2]), "", `forgeqe memory show https://${host}<path> for a page's elements`].join("\n")
+}
+
+export function memoryFlows(dir: string, opts: { steps?: boolean } = {}): string {
+  const flows = readFlows(dir)
+  if (!flows.length) return "No recorded flows yet. A goal is recorded after its first successful live run."
+  const rows = [["PASSED", "STEPS", "REPLAYS", "LAST PASSED", "GOAL"]]
+  for (const f of flows) {
+    rows.push([`${f.successes || 0}/${f.runs || 0}`, String(f.steps.length), String(f.replays || 0), when(f.last_success), clip(f.goal, 70)])
+  }
+  const lines = table(rows, [1, 2])
+  if (opts.steps) {
+    for (const f of flows) {
+      lines.push("", f.goal)
+      f.steps.forEach((s, i) => lines.push(`  ${String(i + 1).padStart(2)}. ${s.line || s.action}`))
+    }
+  }
+  return lines.join("\n")
+}
+
+/** Files that `clear` would delete: everything, or one host's pages and flows. */
+export function memoryFilesFor(dir: string, host?: string): string[] {
+  if (!host) return [...readPages(dir).map((p) => p.file), ...readFlows(dir).map((f) => f.file)]
+  return [
+    ...readPages(dir).filter((p) => hostMatches(p.host, host)).map((p) => p.file),
+    ...readFlows(dir).filter((f) => f.host && hostMatches(f.host, host)).map((f) => f.file),
+  ]
+}
+
+export function clearMemory(files: string[]): void {
+  for (const file of files) rmSync(file, { force: true })
+}

package/src/money.ts

@@ -0,0 +1,39 @@
+/** Region (ISO 3166-1 alpha-2) to the currency people are paid in there. */
+const REGION_CURRENCY: Record<string, string> = {
+  AD: "EUR", AE: "AED", AF: "AFN", AG: "XCD", AI: "XCD", AL: "ALL", AM: "AMD", AO: "AOA", AR: "ARS", AS: "USD", AT: "EUR", AU: "AUD", AW: "AWG", AX: "EUR", AZ: "AZN",
+  BA: "BAM", BB: "BBD", BD: "BDT", BE: "EUR", BF: "XOF", BG: "EUR", BH: "BHD", BI: "BIF", BJ: "XOF", BL: "EUR", BM: "BMD", BN: "BND", BO: "BOB", BQ: "USD", BR: "BRL", BS: "BSD", BT: "BTN", BW: "BWP", BY: "BYN", BZ: "BZD",
+  CA: "CAD", CC: "AUD", CD: "CDF", CF: "XAF", CG: "XAF", CH: "CHF", CI: "XOF", CK: "NZD", CL: "CLP", CM: "XAF", CN: "CNY", CO: "COP", CR: "CRC", CU: "CUP", CV: "CVE", CW: "ANG", CX: "AUD", CY: "EUR", CZ: "CZK",
+  DE: "EUR", DJ: "DJF", DK: "DKK", DM: "XCD", DO: "DOP", DZ: "DZD", EC: "USD", EE: "EUR", EG: "EGP", EH: "MAD", ER: "ERN", ES: "EUR", ET: "ETB", FI: "EUR", FJ: "FJD", FK: "FKP", FM: "USD", FO: "DKK", FR: "EUR",
+  GA: "XAF", GB: "GBP", GD: "XCD", GE: "GEL", GF: "EUR", GG: "GBP", GH: "GHS", GI: "GIP", GL: "DKK", GM: "GMD", GN: "GNF", GP: "EUR", GQ: "XAF", GR: "EUR", GT: "GTQ", GU: "USD", GW: "XOF", GY: "GYD",
+  HK: "HKD", HN: "HNL", HR: "EUR", HT: "HTG", HU: "HUF", ID: "IDR", IE: "EUR", IL: "ILS", IM: "GBP", IN: "INR", IO: "USD", IQ: "IQD", IR: "IRR", IS: "ISK", IT: "EUR", JE: "GBP", JM: "JMD", JO: "JOD", JP: "JPY",
+  KE: "KES", KG: "KGS", KH: "KHR", KI: "AUD", KM: "KMF", KN: "XCD", KP: "KPW", KR: "KRW", KW: "KWD", KY: "KYD", KZ: "KZT", LA: "LAK", LB: "LBP", LC: "XCD", LI: "CHF", LK: "LKR", LR: "LRD", LS: "LSL", LT: "EUR", LU: "EUR", LV: "EUR", LY: "LYD",
+  MA: "MAD", MC: "EUR", MD: "MDL", ME: "EUR", MF: "EUR", MG: "MGA", MH: "USD", MK: "MKD", ML: "XOF", MM: "MMK", MN: "MNT", MO: "MOP", MP: "USD", MQ: "EUR", MR: "MRU", MS: "XCD", MT: "EUR", MU: "MUR", MV: "MVR", MW: "MWK", MX: "MXN", MY: "MYR", MZ: "MZN",
+  NA: "NAD", NC: "XPF", NE: "XOF", NF: "AUD", NG: "NGN", NI: "NIO", NL: "EUR", NO: "NOK", NP: "NPR", NR: "AUD", NU: "NZD", NZ: "NZD", OM: "OMR", PA: "PAB", PE: "PEN", PF: "XPF", PG: "PGK", PH: "PHP", PK: "PKR", PL: "PLN", PM: "EUR", PN: "NZD", PR: "USD", PS: "ILS", PT: "EUR", PW: "USD", PY: "PYG",
+  QA: "QAR", RE: "EUR", RO: "RON", RS: "RSD", RU: "RUB", RW: "RWF", SA: "SAR", SB: "SBD", SC: "SCR", SD: "SDG", SE: "SEK", SG: "SGD", SH: "SHP", SI: "EUR", SJ: "NOK", SK: "EUR", SL: "SLE", SM: "EUR", SN: "XOF", SO: "SOS", SR: "SRD", SS: "SSP", ST: "STN", SV: "USD", SX: "ANG", SY: "SYP", SZ: "SZL",
+  TC: "USD", TD: "XAF", TG: "XOF", TH: "THB", TJ: "TJS", TK: "NZD", TL: "USD", TM: "TMT", TN: "TND", TO: "TOP", TR: "TRY", TT: "TTD", TV: "AUD", TW: "TWD", TZ: "TZS", UA: "UAH", UG: "UGX", US: "USD", UY: "UYU", UZ: "UZS", VA: "EUR", VC: "XCD", VE: "VES", VG: "USD", VI: "USD", VN: "VND", VU: "VUV",
+  WF: "XPF", WS: "WST", YE: "YER", YT: "EUR", ZA: "ZAR", ZM: "ZMW", ZW: "ZWG",
+}
+
+/** ISO 4217 currency for a locale (en-GB → GBP). Unknown regions fall back to USD. */
+export function currencyForLocale(locale?: string): string {
+  const tag = locale || Intl.DateTimeFormat().resolvedOptions().locale || "en-US"
+  try {
+    const region = new Intl.Locale(tag).maximize().region
+    if (region && REGION_CURRENCY[region]) return REGION_CURRENCY[region]
+  } catch {
+    /* not a locale tag */
+  }
+  return "USD"
+}
+
+/** An ISO currency code Intl can format, or undefined. */
+export function currencyCode(raw: string): string | undefined {
+  const code = raw.trim().toUpperCase()
+  if (!/^[A-Z]{3}$/.test(code)) return undefined
+  try {
+    Intl.NumberFormat("en", { style: "currency", currency: code }).format(0)
+    return code
+  } catch {
+    return undefined
+  }
+}

package/src/monitor/alerts.ts

@@ -0,0 +1,94 @@
+import type { MonitorAlerts } from "../config.ts"
+import { failureShot, noticeEmail, sendNotice, teamsCard, type Notice, type SendDeps, type Sent } from "../notify/notice.ts"
+import type { AlertItem } from "./state.ts"
+
+export type { Sent }
+
+/** One alert per round, covering every check that started failing, is still failing, or recovered. */
+export type AlertMessage = {
+  title: string
+  items: AlertItem[]
+  /** The round: when it ran, how many checks passed, and where its report is. */
+  at: string
+  passed: number
+  total: number
+  report?: string
+  reportUrl?: string
+  test?: boolean
+}
+
+const MAX_ATTACHMENTS = 5
+
+function firstLine(s: string, max = 300): string {
+  const line = s.split("\n").find((l) => l.trim()) || ""
+  return line.length <= max ? line.trim() : `${line.trim().slice(0, max - 1)}…`
+}
+
+function clock(iso: string): string {
+  const d = new Date(iso)
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`
+}
+
+/** "45m", "2h 10m", "3d 4h": how long since `from`. */
+export function elapsed(from: string, to: string): string {
+  const mins = Math.max(0, Math.round((Date.parse(to) - Date.parse(from)) / 60_000))
+  if (mins < 60) return `${mins}m`
+  const h = Math.floor(mins / 60)
+  if (h < 24) return `${h}h${mins % 60 ? ` ${mins % 60}m` : ""}`
+  return `${Math.floor(h / 24)}d${h % 24 ? ` ${h % 24}h` : ""}`
+}
+
+const failing = (i: AlertItem) => i.kind !== "recovered"
+
+export function alertTitle(items: AlertItem[]): string {
+  const down = items.filter(failing)
+  const up = items.filter((i) => !failing(i))
+  if (down.length && up.length) return `${down.length} failing, ${up.length} recovered`
+  if (down.length) return down.length === 1 ? `${down[0].title} is failing` : `${down.length} checks are failing`
+  return up.length === 1 ? `${up[0].title} recovered` : `${up.length} checks recovered`
+}
+
+/** One line per item, e.g. "✗ SHOP-12 Checkout: failing since 14:15 (3 rounds)". */
+export function itemLine(i: AlertItem, at: string): string {
+  const name = `${i.id} ${i.title}`
+  if (i.kind === "recovered") return `✓ ${name}: recovered after ${elapsed(i.since, at)}`
+  const rounds = i.failures > 1 ? ` (${i.failures} rounds)` : ""
+  return `✗ ${name}: ${i.kind === "failing" ? "failing" : "still failing"} since ${clock(i.since)}${rounds}`
+}
+
+function itemDetail(i: AlertItem): string[] {
+  if (i.kind === "recovered") return []
+  const step = i.result?.stepResults?.find((v) => v.status === "failed")
+  return [firstLine(i.summary), step ? `Step ${step.step} failed${step.actual ? `: ${firstLine(step.actual, 200)}` : ""}` : ""].filter(Boolean)
+}
+
+/** The round as a notice: the same card and email every other ForgeQE notification uses. */
+export function monitorNotice(m: AlertMessage): Notice {
+  return {
+    source: "ForgeQE monitor",
+    title: m.title,
+    status: m.items.some(failing) ? "bad" : "good",
+    subtitle: `${m.test ? "Test alert · " : ""}Round at ${clock(m.at)} · ${m.passed}/${m.total} checks passing`,
+    items: m.items.map((i) => ({
+      line: itemLine(i, m.at),
+      status: failing(i) ? "bad" : "good",
+      details: itemDetail(i),
+      ...(i.result?.case.url ? { links: [{ title: "Test case", url: i.result.case.url }] } : {}),
+    })),
+    ...(m.reportUrl ? { actions: [{ title: "Open report", url: m.reportUrl }] } : {}),
+    ...(m.report && !m.reportUrl ? { note: `Report: ${m.report}` } : {}),
+    attachments: m.items
+      .filter(failing)
+      .map((i) => failureShot(i.result?.runDir, i.id))
+      .filter((a): a is { filename: string; path: string } => Boolean(a))
+      .slice(0, MAX_ATTACHMENTS),
+  }
+}
+
+export const teamsPayload = (m: AlertMessage) => teamsCard(monitorNotice(m))
+export const emailContent = (m: AlertMessage) => noticeEmail(monitorNotice(m))
+
+/** Send the round to every configured channel; a channel that fails does not stop the others. */
+export function sendAlerts(alerts: MonitorAlerts, m: AlertMessage, deps: SendDeps = {}): Promise<Sent[]> {
+  return sendNotice(alerts, monitorNotice(m), deps)
+}

package/src/monitor/background.ts

@@ -0,0 +1,68 @@
+import type { Card } from "../card.ts"
+import { lockMonitor, roundCard, runMonitor, type MonitorOptions, type RoundResult } from "./run.ts"
+
+/** A monitor running inside this process (the shell, or `forgeqe mcp`) until it is stopped or the process ends. */
+export type BackgroundMonitor = {
+  outDir: string
+  checks: string[]
+  everyMs: number
+  startedAt: Date
+  rounds: number
+  last?: RoundResult
+  nextAt?: Date
+  error?: string
+  stop(): void
+  done: Promise<number>
+}
+
+const running = new Map<string, BackgroundMonitor>()
+
+export function backgroundMonitors(): BackgroundMonitor[] {
+  return [...running.values()]
+}
+
+/** Start rounds in the background; each round is reported as a card. Throws when a monitor already uses the folder. */
+export function startBackgroundMonitor(opts: MonitorOptions & { onCard?: (card: Card) => void; cwd?: string }): BackgroundMonitor {
+  const outDir = opts.config.monitor.outDir
+  const other = running.get(outDir)
+  if (other) throw new Error(`A monitor is already running in ${outDir} (${other.checks.join(" ")}). Stop it first.`)
+  lockMonitor(outDir)()
+  const controller = new AbortController()
+  const bg: BackgroundMonitor = {
+    outDir,
+    checks: opts.checks,
+    everyMs: opts.config.monitor.everyMs,
+    startedAt: new Date(),
+    rounds: 0,
+    stop: () => controller.abort(),
+    done: Promise.resolve(0),
+  }
+  bg.done = runMonitor({
+    ...opts,
+    signal: controller.signal,
+    onRound: (r, nextAt) => {
+      bg.rounds++
+      bg.last = r
+      bg.nextAt = nextAt
+      opts.onCard?.(roundCard(r, nextAt, opts.cwd))
+    },
+  })
+    .catch((err) => {
+      bg.error = (err as Error).message || String(err)
+      opts.onCard?.({ status: "fail", title: "Monitor stopped", body: [bg.error] })
+      return 1
+    })
+    .finally(() => {
+      if (running.get(outDir) === bg) running.delete(outDir)
+    })
+  running.set(outDir, bg)
+  return bg
+}
+
+/** Stop the monitor on `outDir`, or every one; resolves once their rounds have wound down. */
+export async function stopBackgroundMonitors(outDir?: string): Promise<BackgroundMonitor[]> {
+  const picked = outDir ? backgroundMonitors().filter((m) => m.outDir === outDir) : backgroundMonitors()
+  for (const m of picked) m.stop()
+  await Promise.all(picked.map((m) => m.done))
+  return picked
+}