@capagents/forgeqe 1.1.3 → 1.1.4

package/src/capabilities/guide.ts

@@ -15,9 +15,9 @@ import { describeRequirement } from "./status.ts"
 const root = path.resolve(import.meta.dir, "..", "..")
 export const GUIDE_FILE = path.join(root, "docs", "user-guide.html")
 const THEME_SOURCE = path.join(root, "docs", "security-data-flow.html")
-const GUIDE_LOGO_LIGHT_FILE = "/Users/oldguard/Documents/GitHub/test-agent-nexus/public/forge-qe-ai-logo.png"
-const GUIDE_LOGO_DARK_FILE = "/Users/oldguard/Documents/GitHub/test-agent-nexus/public/forge-qe-ai-logo-white.png"
-const PARTNER_LOGO_FILE = "/Users/oldguard/Documents/GitHub/test-agent-nexus/public/assets/capgemini-logo.svg"
+const GUIDE_LOGO_LIGHT_FILE = path.join(root, "assets", "forgeqe-logo.png")
+const GUIDE_LOGO_DARK_FILE = path.join(root, "assets", "forgeqe-logo-white.png")
+const PARTNER_LOGO_FILE = path.join(root, "assets", "capgemini-logo.svg")
 
 /** Chapters that are not a capability area: which HOW_TO_USE sections they hold, in order. */
 const START: DocRef[] = ["What you need to run", "Quick start", "1. Install", "2. Scaffold config"].map((heading) => ({ doc: "HOW_TO_USE.md", heading }))

package/src/cli/help.ts

@@ -38,9 +38,11 @@ Usage:
   forgeqe mcp [--repo DIR] [--profile name] [--url URL] [--headed] [--browser-provider local|browserstack|testmu]
                                                ForgeQE's tools as an MCP server on stdio, for other agents
   forgeqe mcp list                            the Azure DevOps, Jira and other MCP servers ForgeQE's agent gets
-  forgeqe bi [build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR]
-                                               export ForgeQE + ADO/Jira datasets into an Evidence project and build static BI HTML
-  forgeqe bi init                             scaffold or refresh the managed Evidence project files
+  forgeqe bi [build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR] [--static | --evidence]
+                                               export ForgeQE + ADO/Jira datasets into an Evidence project and build a static
+                                               site; without Node.js or when Evidence fails, ForgeQE's own page (--static: always,
+                                               --evidence: fail instead)
+  forgeqe bi init                             scaffold the Evidence project and install its packages
   forgeqe bi sync                             refresh the CSV datasets and generated Evidence pages, without building
   forgeqe pr-tests [pr] [--base BRANCH] [--agent] [--run] [--post]
                                                the tests a pull request (or the commits since BRANCH) can break; --run runs
@@ -138,8 +140,9 @@ The report is report.html (step verdicts, timeline with screenshots, timings, en
 out/suites/<time>/; every run folder also has its own report.html.
 
 Static BI (bi: in forgeqe.yaml): \`forgeqe bi\` writes curated CSV datasets from ForgeQE's own suite and readiness
-reports plus optional Azure DevOps WIQL and Jira JQL datasets, scaffolds an Evidence project, and runs
-\`evidence build\` to produce static HTML in the build directory. No server stays up between runs.
+reports plus optional Azure DevOps WIQL and Jira JQL datasets, scaffolds an Evidence project (@evidence-dev/evidence
+40.x, needs Node.js), and runs \`evidence sources\` and \`evidence build\` to produce a static site in the build directory;
+when that cannot run, it writes ForgeQE's own self-contained page instead. No server stays up between runs.
 
 Healing (forgeqe heal): ForgeQE runs the tests (the command given, code.test_command, or one the agent finds).
 For each failing test, Scribe re-runs its flow in the real browser: when the flow still works, the test is out

package/src/cli/index.ts

@@ -217,7 +217,7 @@ export async function main(argv: string[]): Promise<number> {
         const cfg = loadConfig(configOpts(flags))
         const trends = positionals[1] === "trends"
         const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
-    const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
+        const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
         const out = (await TOOLS.find((t) => t.name === (trends ? "quality_trends" : "quality_report"))!.run(trends ? { page: positionals[2] } : { run_dir: positionals[1] }, ctx)) as { budget_exceeded?: unknown[]; pages?: { slower: unknown[]; newly_failing_rules: unknown[] }[] }
         return out.budget_exceeded?.length || out.pages?.some((p) => p.slower.length || p.newly_failing_rules.length) ? 1 : 0
       }
@@ -382,7 +382,7 @@ async function cmdApi(args: string[], flags: Flags): Promise<number> {
   const cfg = loadConfig(configOpts(flags))
   const action = args[0] || "list"
   const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
-    const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
+  const ctx: ToolContext = { config: cfg, cwd: process.cwd(), session: "once", emit: toolPrinter(color, (line) => console.log(line), detailOf(flags)) }
   const tool = (name: string) => TOOLS.find((t) => t.name === name)!
   const csv = (name: string) => (strFlag(flags, name) || "").split(",").map((s) => s.trim()).filter(Boolean)
   switch (action) {
@@ -489,11 +489,16 @@ async function cmdBi(args: string[], flags: Flags): Promise<number> {
     dataDir: strFlag(flags, "data-dir"),
     buildDir: strFlag(flags, "build-dir") || strFlag(flags, "out"),
   }
+  const shown = (file: string) => path.relative(process.cwd(), file) || file
+  const printNotes = (notes: string[]) => {
+    for (const note of notes) console.log(`note              ${note}`)
+  }
   switch (action) {
     case "init": {
       const out = await initBiProject(cfg, overrides)
       console.log(`Evidence project  ${out.evidenceDir}`)
-      for (const file of out.files) console.log(`generated         ${path.relative(process.cwd(), file) || file}`)
+      for (const file of out.files) console.log(`generated         ${shown(file)}`)
+      printNotes(out.notes)
       return 0
     }
     case "sync": {
@@ -505,23 +510,30 @@ async function cmdBi(args: string[], flags: Flags): Promise<number> {
       console.log(`Case results      ${out.caseResults}`)
       console.log(`Readiness reports ${out.readinessReports}`)
       console.log(`External datasets ${out.externalDatasets}`)
-      console.log(`Summary           ${path.relative(process.cwd(), out.summaryFile) || out.summaryFile}`)
+      console.log(`Summary           ${shown(out.summaryFile)}`)
+      printNotes(out.notes)
       return 0
     }
     case "build": {
-      const out = await buildBi(cfg, overrides)
+      const out = await buildBi(cfg, overrides, boolFlag(flags, "static") ? "static" : boolFlag(flags, "evidence") ? "evidence" : "auto")
       console.log(`Evidence project  ${out.evidenceDir}`)
       console.log(`Static site       ${out.buildDir}`)
-      console.log(`Index             ${path.relative(process.cwd(), out.indexFile) || out.indexFile}`)
-      console.log(`Summary           ${path.relative(process.cwd(), out.summaryFile) || out.summaryFile}`)
+      console.log(`Index             ${shown(out.indexFile)}`)
+      console.log(`Summary           ${shown(out.summaryFile)}`)
       console.log(`Suite runs        ${out.suites}`)
       console.log(`Case results      ${out.caseResults}`)
       console.log(`Readiness reports ${out.readinessReports}`)
       console.log(`External datasets ${out.externalDatasets}`)
+      if (out.engine === "evidence") {
+        console.log("Built with        Evidence. Serve the folder to view it (npx serve, or evidence preview): opened from disk it cannot load its data.")
+      } else {
+        console.log(`Built with        ForgeQE's own page, without Evidence (${out.fallbackReason}). It opens straight from disk.`)
+      }
+      printNotes(out.notes)
       return 0
     }
     default:
-      throw new Error("Usage: forgeqe bi [init|sync|build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR]")
+      throw new Error("Usage: forgeqe bi [init|sync|build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR] [--static | --evidence]")
   }
 }
 

package/src/config.ts

@@ -63,20 +63,6 @@ export type MemoryConfig = {
   replay: ReplayMode
 }
 
-export type CacheConfig = {
-  enabled: boolean
-  /** Redis connection string, e.g. redis://127.0.0.1:6379. */
-  redisUrl: string
-  /** Prefix for every Redis key this ForgeQE workspace writes. */
-  keyPrefix: string
-  /** Default TTL for cached JSON payloads, in seconds. */
-  defaultTtlSeconds: number
-  /** TTL for BI external dataset exports, in seconds. */
-  biTtlSeconds: number
-  /** Socket connect timeout for Redis, in milliseconds. */
-  connectTimeoutMs: number
-}
-
 function runtimeBin(value: unknown, base: string): string | undefined {
   if (!value) return undefined
   const s = String(value)
@@ -348,8 +334,6 @@ export type AppConfig = {
   configPath?: string
   /** `mcp:` in forgeqe.yaml: more MCP servers for ForgeQE's agent, by name. */
   mcp?: Record<string, ExtraMcpServer>
-  /** Optional Redis-backed cache for deterministic external data fetches. */
-  cache?: CacheConfig
   activeProfile: string
   profiles: Record<string, LlmProfile>
   llm: LlmProfile
@@ -410,22 +394,6 @@ function domainConfig(raw: unknown): DomainConfig | undefined {
   return { industry, regulations, ...(d.notes ? { notes: String(d.notes).trim() } : {}) }
 }
 
-function cacheConfig(raw: unknown): CacheConfig | undefined {
-  const c = asRecord(raw)
-  const asked = raw !== undefined || Boolean(process.env.FORGEQE_REDIS_URL)
-  if (!asked || c.enabled === false) return undefined
-  const redisUrl = String(c.redis_url || c.url || process.env.FORGEQE_REDIS_URL || "").trim()
-  if (!redisUrl) throw new Error('cache.redis_url is required when cache is enabled. Example: cache: { redis_url: "redis://127.0.0.1:6379" }')
-  return {
-    enabled: true,
-    redisUrl,
-    keyPrefix: String(c.key_prefix || "forgeqe").trim() || "forgeqe",
-    defaultTtlSeconds: positiveInt(c.default_ttl_seconds, 3600, "cache.default_ttl_seconds"),
-    biTtlSeconds: positiveInt(c.bi_ttl_seconds, 900, "cache.bi_ttl_seconds"),
-    connectTimeoutMs: positiveInt(c.connect_timeout_ms, 3000, "cache.connect_timeout_ms"),
-  }
-}
-
 export function replayMode(raw: unknown): ReplayMode {
   const mode = String(raw || "verify").toLowerCase()
   if (mode === "trust" || mode === "off") return mode
@@ -471,12 +439,12 @@ const REMOTE_BROWSER_DEFAULTS: Record<RemoteBrowserProvider, Pick<BrowserRemoteC
   browserstack: {
     usernameEnv: "BROWSERSTACK_USERNAME",
     accessKeyEnv: "BROWSERSTACK_ACCESS_KEY",
-    endpoint: "wss://cdp.browserstack.com/playwright",
+    endpoint: "wss://cdp.browserstack.com/puppeteer",
   },
   testmu: {
     usernameEnv: "LT_USERNAME",
     accessKeyEnv: "LT_ACCESS_KEY",
-    endpoint: "wss://cdp.lambdatest.com/playwright",
+    endpoint: "wss://cdp.lambdatest.com/puppeteer",
   },
 }
 
@@ -545,6 +513,10 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   const defaults = REMOTE_BROWSER_DEFAULTS[provider]
   const browser = String(remote.browser || "").trim()
   if (!browser) throw new Error(`${where}.remote.browser is required when browser.provider is ${provider}.`)
+  // The engine drives the browser over the Chrome DevTools Protocol, so the grid must hand back a Chromium browser.
+  if (!/chrome|edge|chromium/i.test(browser) || /^(playwright|pw)-/i.test(browser)) {
+    throw new Error(`${where}.remote.browser is "${browser}": ForgeQE drives remote browsers over the Chrome DevTools Protocol, so use chrome or edge.`)
+  }
   const browserVersion = String(remote.browser_version || remote.browserVersion || "latest").trim() || "latest"
   const os = String(remote.os || "").trim() || undefined
   const osVersion = String(remote.os_version || remote.osVersion || "").trim() || undefined
@@ -555,12 +527,16 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   if (provider === "testmu" && !platform && !os) {
     throw new Error(`${where}.remote.platform is required when browser.provider is testmu, or set ${where}.remote.os (and optionally os_version).`)
   }
+  const endpoint = String(remote.endpoint || defaults.endpoint).trim().replace(/\/+$/, "")
+  if (/\/playwright$/i.test(endpoint)) {
+    throw new Error(`${where}.remote.endpoint ${endpoint} speaks Playwright's own protocol; ForgeQE needs the CDP endpoint (${defaults.endpoint}).`)
+  }
   const extra = objectMap(remote.extra ?? remote.capabilities, `${where}.remote.extra`)
   return {
     provider,
     usernameEnv: String(remote.username_env || remote.usernameEnv || defaults.usernameEnv),
     accessKeyEnv: String(remote.access_key_env || remote.accessKeyEnv || defaults.accessKeyEnv),
-    endpoint: String(remote.endpoint || defaults.endpoint).trim().replace(/\/+$/, ""),
+    endpoint,
     browser,
     browserVersion,
     ...(os ? { os } : {}),
@@ -779,7 +755,6 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
   const config: AppConfig = {
     configPath,
     mcp: extraMcpServers(yaml.mcp, base),
-    cache: cacheConfig(yaml.cache),
     activeProfile,
     profiles,
     llm: profiles[activeProfile] || { ...NO_PROFILE },
@@ -1076,9 +1051,12 @@ function apiConfig(a: Record<string, unknown>): ApiConfig {
   }
 }
 
+/** The tables forgeqe bi always exports; a dataset id may not reuse one. */
+export const BI_BUILTIN_TABLES = ["suites", "case_results", "step_results", "writebacks", "readiness", "readiness_stories", "readiness_cases", "external_datasets"]
+
 function biConfig(b: Record<string, unknown>, base: string, outDir: string, configPath: string | undefined): BiConfig {
   const evidenceDir = path.resolve(base, String(b.evidence_dir || path.join(".", "evidence")))
-  const defaultDataDir = path.join(evidenceDir, "sources", "forgeqe", "data")
+  const defaultDataDir = path.join(evidenceDir, "sources", "forgeqe")
   const title = String(b.title || "ForgeQE BI").trim() || "ForgeQE BI"
   const datasets = Object.entries(asRecord(b.datasets)).map(([id, value]) => biDataset(id, asRecord(value)))
   return {
@@ -1091,7 +1069,9 @@ function biConfig(b: Record<string, unknown>, base: string, outDir: string, conf
 }
 
 function biDataset(id: string, raw: Record<string, unknown>): BiDatasetConfig {
-  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`bi.datasets.${id}: ids may only use letters, digits, - and _.`)
+  // The id is the dataset's table name in Evidence's SQL (forgeqe.<id>), so it must be a plain identifier.
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(id)) throw new Error(`bi.datasets.${id}: ids may only use letters, digits and _, and must not start with a digit.`)
+  if (BI_BUILTIN_TABLES.includes(id)) throw new Error(`bi.datasets.${id}: ${id} is one of ForgeQE's own BI tables; choose another id.`)
   const title = String(raw.title || id.replace(/[-_]+/g, " ").trim()).trim()
   const kind = String(raw.kind || "").trim().toLowerCase()
   if (kind === "ado_wiql") {

package/src/run.ts

@@ -181,6 +181,11 @@ export async function executeRun(opts: ExecuteOptions): Promise<{ result: RunRes
 
   const missing = missingKey(opts.config.llm)
   if (missing) throw new Error(missing)
+  // A remote grid's keys are checked here, before the engine starts, rather than failing inside it.
+  if (browser.remote) {
+    const unset = [browser.remote.usernameEnv, browser.remote.accessKeyEnv].filter((name) => !process.env[name]?.trim())
+    if (unset.length) throw new Error(`${browser.provider}: set ${unset.join(" and ")} in the environment, or save them with "forgeqe auth login ${browser.provider}".`)
+  }
   const log = (text: string) => opts.onEvent?.({ type: "log", level: "info", text })
   const python = await ensureEngine(log)
   // The browser agent's added instructions: forgeqe.yaml's, prompts/browser-extra.md, and the product knowledge that matches the goal.

package/testmu.example.yaml

@@ -1,6 +1,6 @@
 provider: testmu
 remote:
-  browser: pw-chromium
+  browser: Chrome
   browser_version: latest
   platform: Windows 11
   username_env: LT_USERNAME
@@ -9,6 +9,5 @@ remote:
   build: nightly
   name: checkout smoke
   local: false
-  extra:
-    "lt:options":
-      console: true
+  extra:                 # merged into LT:Options, so keys go straight here
+    console: true

package/src/cache.ts

@@ -1,92 +0,0 @@
-import { createHash } from "node:crypto"
-
-import { createClient } from "redis"
-
-import type { CacheConfig } from "./config.ts"
-
-type CacheAdapter = {
-  get(key: string): Promise<string | null>
-  set(key: string, value: string, ttlSeconds: number): Promise<void>
-}
-
-let factoryOverride: ((config: CacheConfig) => Promise<CacheAdapter | null>) | undefined
-const adapters = new Map<string, Promise<CacheAdapter | null>>()
-
-function keyFor(config: CacheConfig): string {
-  return `${config.redisUrl}\n${config.keyPrefix}\n${config.connectTimeoutMs}`
-}
-
-function fullKey(config: CacheConfig, namespace: string, parts: unknown[]): string {
-  const digest = createHash("sha256").update(JSON.stringify(parts)).digest("hex")
-  return `${config.keyPrefix}:${namespace}:${digest}`
-}
-
-async function connectRedis(config: CacheConfig): Promise<CacheAdapter | null> {
-  const client = createClient({
-    url: config.redisUrl,
-    socket: { connectTimeout: config.connectTimeoutMs },
-  })
-  client.on("error", () => {})
-  try {
-    await client.connect()
-  } catch {
-    try {
-      client.disconnect()
-    } catch {}
-    return null
-  }
-  return {
-    async get(key) {
-      try {
-        return await client.get(key)
-      } catch {
-        return null
-      }
-    },
-    async set(key, value, ttlSeconds) {
-      try {
-        await client.set(key, value, { EX: ttlSeconds })
-      } catch {}
-    },
-  }
-}
-
-async function adapter(config: CacheConfig | undefined): Promise<CacheAdapter | null> {
-  if (!config?.enabled || !config.redisUrl) return null
-  const id = keyFor(config)
-  if (!adapters.has(id)) {
-    adapters.set(id, (factoryOverride || connectRedis)(config))
-  }
-  return adapters.get(id)!
-}
-
-export async function cachedJson<T>(
-  config: CacheConfig | undefined,
-  opts: {
-    namespace: string
-    keyParts: unknown[]
-    ttlSeconds?: number
-    load: () => Promise<T>
-  },
-): Promise<T> {
-  const ttlSeconds = opts.ttlSeconds || config?.defaultTtlSeconds || 3600
-  const store = await adapter(config)
-  if (!store) return opts.load()
-  const key = fullKey(config!, opts.namespace, opts.keyParts)
-  const hit = await store.get(key)
-  if (hit !== null) {
-    try {
-      return JSON.parse(hit) as T
-    } catch {
-      // Bad JSON should not break the current run; reload and overwrite it.
-    }
-  }
-  const value = await opts.load()
-  await store.set(key, JSON.stringify(value), ttlSeconds)
-  return value
-}
-
-export function setCacheFactoryForTests(factory?: (config: CacheConfig) => Promise<CacheAdapter | null>): void {
-  factoryOverride = factory
-  adapters.clear()
-}