@capagents/forgeqe 1.3.1 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "MIT",
   "type": "module",

package/py/forgeqe_engine/cli.py

@@ -171,8 +171,18 @@ def _token(out: TextIO) -> int:
         return 1
 
 
+def _utf8_stdio() -> None:
+    """The CLI speaks UTF-8 on every pipe; on Windows a pipe defaults to the ANSI code page, which turns a curly quote into a lone surrogate."""
+    for stream in (sys.stdin, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
 def main(argv: list[str] | None = None) -> int:
     args = list(sys.argv[1:] if argv is None else argv)
+    _utf8_stdio()
     out = _event_stream()
     _configure_env()
     cmd = args[0] if args else "run"

package/py/forgeqe_engine/summary.py

@@ -81,6 +81,12 @@ def _error_summary_from_history(history: Any) -> str:
         n = len(errs)
         if len(distinct) == 1:
             msg = distinct[0]
+            if n > 1 and "surrogates not allowed" in msg:
+                return (
+                    f"Run stopped after {n} identical errors: {msg}. "
+                    "The request to the model held text that was decoded in the wrong encoding, so it was never sent; "
+                    "the LLM provider is not at fault. Update ForgeQE; the engine now reads its input as UTF-8."
+                )
             if n > 1:
                 return (
                     f"Run stopped after {n} identical errors: {msg}. "

package/src/cases/defects.ts

@@ -196,7 +196,8 @@ export class DefectBook {
       .filter(({ p }) => !this.noise.has(problemKey(p)))
       // The strongest kind; of those, the one nearest the failure (the latest step).
       .sort((a, b) => rank(a.p) - rank(b.p) || b.step - a.step)[0]?.p
-    const page = r.finalUrl ? pageKey(r.finalUrl) : undefined
+    // about:blank and other non-web pages are no page: their key would read "nullblank".
+    const page = r.finalUrl && /^https?:/i.test(r.finalUrl) ? pageKey(r.finalUrl) : undefined
     if (evidence) {
       const key = problemKey(evidence)
       const term = problemTerm(evidence)

package/src/engine/setup.ts

@@ -68,6 +68,9 @@ export function engineEnv(extra?: Record<string, string>, allow: string[] = []):
   const env = allowListEnv(process.env, allow)
   env.PYTHONPATH = [ENGINE_SOURCE, env.PYTHONPATH].filter(Boolean).join(path.delimiter)
   env.PYTHONUNBUFFERED = "1"
+  // Requests, prompts and logs are UTF-8; Windows would otherwise read pipes and files in its ANSI code page.
+  env.PYTHONUTF8 = "1"
+  env.PYTHONIOENCODING = "utf-8"
   return { ...env, ...extra }
 }
 

package/src/update.ts

@@ -1,5 +1,6 @@
-import { spawnSync } from "node:child_process"
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { spawn, spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
 import path from "node:path"
 import { packageVersion } from "./tui/theme.ts"
 
@@ -28,19 +29,50 @@ export interface UpdateDeps {
   platform: NodeJS.Platform
   sleep: (ms: number) => Promise<void>
   now: () => number
+  /**
+   * Windows: starts `script` (a .cmd) detached, to run once this process has exited, and returns its log file.
+   * A running ForgeQE keeps files of its own install open (its launcher, native libraries), and Windows does not
+   * let an installer replace a file that is in use, so the update cannot run from inside ForgeQE.
+   */
+  defer?: (script: string) => string
+}
+
+/**
+ * How to start `cmd` on `platform`. Windows runs .cmd and .bat files (npm, pyenv-win) only through a shell, which Node
+ * refuses to do on its own (EINVAL), so those go through cmd.exe with each argument quoted.
+ */
+export function spawnPlan(cmd: string, args: string[], platform: NodeJS.Platform): { cmd: string; args: string[]; shell: boolean } {
+  if (platform !== "win32" || /\.exe$/i.test(cmd)) return { cmd, args, shell: false }
+  return { cmd: winQuote(cmd), args: args.map(winQuote), shell: true }
+}
+
+/** One argument for cmd.exe: quoted when it has a space or a character cmd.exe would read. */
+export function winQuote(a: string): string {
+  return /[\s&|<>^()%!"]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a
 }
 
 export function defaultDeps(): UpdateDeps {
   return {
     fetch,
     run: (cmd, args) => {
-      const r = spawnSync(cmd, args, { encoding: "utf8" })
+      const plan = spawnPlan(cmd, args, process.platform)
+      const r = spawnSync(plan.cmd, plan.args, { encoding: "utf8", shell: plan.shell, windowsHide: true })
       return { status: r.error ? null : r.status, stdout: r.stdout || "", stderr: r.stderr || (r.error ? String(r.error.message) : "") }
     },
     env: process.env,
     platform: process.platform,
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     now: () => Date.now(),
+    defer: (script) => {
+      const dir = path.join(tmpdir(), "forgeqe-update")
+      mkdirSync(dir, { recursive: true })
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+      const file = path.join(dir, `update-${stamp}.cmd`)
+      const log = path.join(dir, `update-${stamp}.log`)
+      writeFileSync(file, script.replace(/\{LOG\}/g, log).replace(/\n/g, "\r\n"))
+      spawn("cmd.exe", ["/d", "/c", file], { detached: true, stdio: "ignore", windowsHide: true }).unref()
+      return log
+    },
   }
 }
 
@@ -142,12 +174,33 @@ function packageDirOf(file: string): string | undefined {
   return undefined
 }
 
+/**
+ * The package a `forgeqe` on PATH belongs to when it is a copy or a wrapper, not a link: npm on Windows writes
+ * forgeqe.cmd next to node_modules; bun on Windows writes forgeqe.exe in ~/.bun/bin for ~/.bun/install/global; an npm
+ * prefix elsewhere keeps packages in <prefix>/lib/node_modules.
+ */
+function packageOfShim(binDir: string): string | undefined {
+  const parts = NPM_PACKAGE.split("/")
+  for (const dir of [path.join(binDir, "node_modules", ...parts), path.join(binDir, "..", "install", "global", "node_modules", ...parts), path.join(binDir, "..", "lib", "node_modules", ...parts)]) {
+    const found = packageDirOf(path.join(dir, "package.json"))
+    if (found) return path.resolve(found)
+  }
+  return undefined
+}
+
 function pythonOfScript(script: string, platform: NodeJS.Platform): string | undefined {
   if (platform === "win32") {
     const dir = path.dirname(script)
-    if (path.basename(dir).toLowerCase() !== "scripts") return undefined
     const python = path.join(path.dirname(dir), "python.exe")
-    return existsSync(python) ? python : undefined
+    if (path.basename(dir).toLowerCase() === "scripts" && existsSync(python)) return python
+    // pip's forgeqe.exe carries the Python it was installed for (`#!C:\...\python.exe` near its end): the way to find
+    // it for `pip install --user`, whose Scripts folder is not next to python.exe.
+    try {
+      const text = readFileSync(script).toString("latin1")
+      const m = [...text.matchAll(/#!\s*"?([^"\r\n]*?pythonw?\.exe)"?/gi)].pop()
+      if (m && existsSync(m[1])) return m[1]
+    } catch {}
+    return undefined
   }
   let first = ""
   try {
@@ -182,7 +235,10 @@ export function findInstalls(deps: UpdateDeps): Install[] {
       }
       if (seen.has(target)) continue
       seen.add(target)
-      const pkgDir = packageDirOf(target)
+      const pkgDir = packageDirOf(target) || packageOfShim(dir)
+      // npm on Windows writes forgeqe, forgeqe.cmd and forgeqe.ps1 for one install.
+      if (pkgDir && seen.has(`pkg:${pkgDir}`)) continue
+      if (pkgDir) seen.add(`pkg:${pkgDir}`)
       if (pkgDir) {
         let version = ""
         try {
@@ -233,6 +289,47 @@ export function commandLine([cmd, args]: [string, string[]]): string {
   return [cmd, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")
 }
 
+/** What to do when an installer refuses for a reason the machine sets, not ForgeQE (Linux: root-owned npm, PEP 668). */
+export function failureHint(kind: InstallKind, output: string, platform: NodeJS.Platform): string {
+  if (/EACCES|permission denied/i.test(output) && kind === "npm") {
+    return platform === "win32"
+      ? "npm's global folder is not writable: run the terminal as administrator, or install with bun (bun add -g @capagents/forgeqe)."
+      : "npm's global folder belongs to root: run sudo npm install -g @capagents/forgeqe, or give npm a folder of your own (npm config set prefix ~/.npm-global)."
+  }
+  if (/externally-managed-environment/i.test(output)) {
+    return "This Python is managed by the system and pip will not change it: install with pipx install forgeqe-cli, or in a virtual environment."
+  }
+  if (/EBUSY|EPERM|being used by another process/i.test(output)) {
+    return "A file of the install is in use: close every ForgeQE window and run forgeqe update again."
+  }
+  return ""
+}
+
+/**
+ * The .cmd that updates Windows installs after the ForgeQE that started it has exited: it waits for these processes
+ * (ForgeQE and its launcher), runs each install's commands, and writes everything to {LOG}.
+ */
+export function windowsUpdateScript(steps: { kind: InstallKind; bin: string; commands: Array<[string, string[]]> }[], pids: number[], version: string): string {
+  const lines = ["@echo off", "setlocal", ":wait"]
+  for (const pid of pids.filter((p) => Number.isInteger(p) && p > 0)) {
+    // ping waits a second where timeout cannot (a detached script has no console); System32 paths, so Git's find
+    // or another tasklist on PATH is never the one that runs.
+    lines.push(`"%SystemRoot%\\System32\\tasklist.exe" /FI "PID eq ${pid}" 2>nul | "%SystemRoot%\\System32\\find.exe" " ${pid} " >nul && (ping -n 2 127.0.0.1 >nul & goto wait)`)
+  }
+  lines.push(`echo Updating ForgeQE to ${version} > "{LOG}"`)
+  for (const step of steps) {
+    lines.push(`echo. >> "{LOG}"`, `echo Updating the ${step.kind} install (${step.bin}) >> "{LOG}"`)
+    for (const [cmd, args] of step.commands) {
+      const line = [cmd, ...args].map(winQuote).join(" ")
+      const cacheStep = args[0] === "pm" && args[1] === "cache"
+      lines.push(`echo $ ${line.replace(/[&|<>^]/g, "^$&")} >> "{LOG}"`)
+      lines.push(`call ${line} >> "{LOG}" 2>&1${cacheStep ? "" : ` || echo FAILED: ${step.kind} install >> "{LOG}"`}`)
+    }
+  }
+  lines.push(`echo. >> "{LOG}"`, `echo Done. Open a new terminal and run: forgeqe --version >> "{LOG}"`)
+  return `${lines.join("\n")}\n`
+}
+
 export interface UpdateOptions {
   /** A version to install instead of the latest. */
   version?: string
@@ -283,6 +380,16 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
     }
   }
 
+  if (deps.platform === "win32" && deps.defer) {
+    // Windows will not replace files the running ForgeQE holds open, so the installs update once it has exited.
+    const steps = stale.map((inst) => ({ kind: inst.kind, bin: inst.bin, commands: updateCommands(inst, target, deps.env) }))
+    for (const step of steps) for (const c of step.commands) log(`  $ ${commandLine(c)}`)
+    const logFile = deps.defer(windowsUpdateScript(steps, [process.pid, process.ppid], target))
+    log(`\nThe update to ${target} starts as soon as this command exits (Windows locks the files a running ForgeQE uses).`)
+    log(`It writes what it does to ${logFile}. Then open a new terminal and run forgeqe --version.`)
+    return 0
+  }
+
   let failed = 0
   for (const inst of stale) {
     log(`\nUpdating the ${inst.kind} install (${inst.bin})`)
@@ -293,7 +400,10 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
         const cacheStep = c[1][0] === "pm" && c[1][1] === "cache"
         if (cacheStep) continue
         failed++
-        log((r.stderr || r.stdout).trim().split("\n").slice(-5).map((l) => `  ${l}`).join("\n"))
+        const output = (r.stderr || r.stdout).trim()
+        log(output.split("\n").slice(-5).map((l) => `  ${l}`).join("\n"))
+        const hint = failureHint(inst.kind, output, deps.platform)
+        if (hint) log(`  ${hint}`)
         break
       }
     }
@@ -306,6 +416,6 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
     log(`\n${behind.length || failed} install(s) are still behind ${target}; the output above says why.`)
     return 1
   }
-  log(`\nforgeqe ${target} is installed. Open a new terminal (or run hash -r) if the shell still finds the old one.`)
+  log(`\nforgeqe ${target} is installed. Open a new terminal${deps.platform === "win32" ? "" : " (or run hash -r)"} if the shell still finds the old one.`)
   return 0
 }