@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/suite/run.ts

@@ -0,0 +1,303 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { goalFor, writeBack as postResults, type CaseResult, type TestCase, type WriteBack } from "../cases/index.ts"
+import { costOf } from "../cases/types.ts"
+import { addUsage, NO_USAGE } from "../usage.ts"
+import type { AgentEvent, CodeResult, ReplayMode, RunResult } from "../types.ts"
+import { codeSkipReason, runCodeAgent } from "../code/index.ts"
+import type { AppConfig } from "../config.ts"
+import { fileBugs } from "../cases/bugs.ts"
+import { classifyFailure, FAILURE_LABEL } from "../cases/failure.ts"
+import { associateAdoAutomation, readMappings } from "../code/traceability.ts"
+import type { ExistingTest } from "../code/prompt.ts"
+import { runTestCommand } from "../code/testrun.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import { readTimeline, reportEnv, type ReportEnv } from "../report/html.ts"
+import { executeRun, runDirectory } from "../run.ts"
+import { writeReports } from "./report.ts"
+
+export type SuiteEvent =
+  | { type: "case-start"; index: number; total: number; case: TestCase; runDir: string }
+  | { type: "case-event"; index: number; case: TestCase; event: AgentEvent }
+  | { type: "case-done"; index: number; total: number; result: CaseResult }
+  | { type: "code-start"; index: number; case: TestCase }
+  | { type: "code-done"; index: number; case: TestCase; result: CaseResult }
+  | { type: "writeback"; item: WriteBack }
+
+export type SuiteResult = {
+  name: string
+  dir: string
+  startedAt: string
+  finishedAt: string
+  ms: number
+  results: CaseResult[]
+  writeBack: WriteBack[]
+  files: { junit: string; html: string; json: string }
+  stopped: boolean
+  env?: ReportEnv
+}
+
+export type SuiteOptions = {
+  config: AppConfig
+  cases: TestCase[]
+  /** Repo for the coding agent; unset: browser runs only. */
+  repo?: string
+  parallel?: number
+  outDir?: string
+  writeBack?: boolean
+  headed?: boolean
+  url?: string
+  maxSteps?: number
+  replay?: ReplayMode
+  memory?: boolean
+  /** Browser skills for every case (empty: none); unset: the engine picks per case. */
+  skills?: string[]
+  /** Folder whose .forgeqe/skills count as project skills; default: repo. */
+  skillsRepo?: string
+  signal?: AbortSignal
+  onEvent?: (e: SuiteEvent) => void
+  execute?: typeof executeRun
+  coder?: typeof runCodeAgent
+  /** Replaces runTestCommand for a case's existing test. */
+  runTest?: typeof runTestCommand
+}
+
+const STATUS = { complete: "passed", fail: "failed", stopped: "stopped" } as const
+
+function slug(s: string): string {
+  return s.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "case"
+}
+
+/**
+ * Run each test case as one browser goal, `parallel` at a time. With a repo set, a passed case is handed to the coding
+ * agent as soon as its browser run ends, and that case's worker waits for its test before starting the next case:
+ * explore, hand off, code, then the next case. Coding jobs run one after another so two never edit the repo at once.
+ * Results are posted back to their source, then written as JUnit XML, HTML, and JSON.
+ */
+export async function runSuite(opts: SuiteOptions): Promise<SuiteResult> {
+  const { config, cases } = opts
+  const execute = opts.execute || executeRun
+  const coder = opts.coder || runCodeAgent
+  const emit = opts.onEvent || (() => {})
+  const dir = runDirectory(config.suite.outDir, opts.outDir)
+  mkdirSync(dir, { recursive: true })
+  const t0 = Date.now()
+  const startedAt = new Date(t0).toISOString()
+  const name = `ForgeQE suite ${startedAt.slice(0, 16).replace("T", " ")}`
+  const total = cases.length
+  const results: (CaseResult | undefined)[] = Array.from({ length: total }, () => undefined)
+  const width = String(total).length
+  let codeQueue: Promise<void> = Promise.resolve()
+  /** Written back during the suite: bugs for functional defects (the suite's own bug pass skips those cases) and tests set as a test case's automation. */
+  const earlyBugs: WriteBack[] = []
+
+  const runOne = async (index: number) => {
+    const tc = cases[index]
+    const runDir = path.join(dir, `${String(index + 1).padStart(width, "0")}-${slug(tc.id)}`)
+    mkdirSync(runDir, { recursive: true })
+    writeFileSync(path.join(runDir, "testcase.json"), `${JSON.stringify(tc, null, 2)}\n`)
+    emit({ type: "case-start", index, total, case: tc, runDir })
+    const start = Date.now()
+    const explore = async (): Promise<{ run?: RunResult; error?: string }> => {
+      try {
+        const { result } = await execute({
+          config,
+          goal: goalFor(tc),
+          url: tc.startUrl || opts.url,
+          headed: opts.headed,
+          maxSteps: opts.maxSteps,
+          replay: opts.replay,
+          memory: opts.memory,
+          caseSteps: tc.steps.length,
+          outDir: runDir,
+          skills: opts.skills,
+          repo: opts.skillsRepo || opts.repo,
+          signal: opts.signal,
+          onEvent: (event) => emit({ type: "case-event", index, case: tc, event }),
+        })
+        return { run: result }
+      } catch (err) {
+        return { error: (err as Error).message || String(err) }
+      }
+    }
+    let { run, error } = await explore()
+    let failure = opts.signal?.aborted ? undefined : classifyFailure(run, error)
+    let spent = run?.usage
+    // An environment problem (the site down, a 5xx, a network failure) is often gone a moment later: one more run.
+    let retried = false
+    if (failure?.type === "environment" && !opts.signal?.aborted) {
+      emit({ type: "case-event", index, case: tc, event: { type: "log", level: "warn", text: `${FAILURE_LABEL.environment}: ${failure.reason} Running the case once more.` } })
+      retried = true
+      ;({ run, error } = await explore())
+      failure = opts.signal?.aborted ? undefined : classifyFailure(run, error)
+      spent = run?.usage ? addUsage(spent || NO_USAGE, run.usage) : spent
+    }
+    const end = Date.now()
+    const result: CaseResult = {
+      case: tc,
+      // Steps that passed on a page over an accessibility or performance budget: the case fails on the budget.
+      status: run ? (run.status === "complete" && run.budgetExceeded?.length ? "failed" : STATUS[run.status]) : opts.signal?.aborted ? "stopped" : "error",
+      summary: [run?.summary || error || "", ...(run?.budgetExceeded?.length ? [`Budget exceeded: ${run.budgetExceeded.join("; ")}`] : [])].filter(Boolean).join("\n\n"),
+      startedAt: new Date(start).toISOString(),
+      finishedAt: new Date(end).toISOString(),
+      ms: end - start,
+      tokens: spent ? spent.input + spent.output : 0,
+      ...(spent ? { usage: spent, cost: costOf(spent, config.llm.price) } : {}),
+      runDir,
+      finalUrl: run?.finalUrl || undefined,
+      steps: timelineLines(runDir),
+      ...(run?.caseReport?.steps.length ? { stepResults: run.caseReport.steps } : {}),
+      ...(failure ? { failure } : {}),
+      ...(retried ? { retried } : {}),
+    }
+    results[index] = result
+    emit({ type: "case-done", index, total, result })
+
+    // A functional defect's bug is filed now, so the test written for it can name the bug it waits on.
+    if (failure?.type === "functional_defect" && (opts.writeBack ?? config.sources.writeBack) && config.sources.bugs) {
+      for (const item of await fileBugs([result], config.sources, name)) {
+        earlyBugs.push(item)
+        emit({ type: "writeback", item })
+        if (!item.error) result.bug = { label: item.text.split(":")[0], ...(item.url ? { url: item.url } : {}) }
+      }
+    }
+
+    if (!opts.repo || !config.suite.code || opts.signal?.aborted) return
+    const skip = run ? codeSkipReason(config, run, failure) : "the browser run did not finish"
+    if (skip) {
+      result.codeSkipped = skip
+      return
+    }
+    // This case goes from its browser run straight to the coding agent, and its worker waits for that before taking
+    // the next case. Coding jobs still queue one after another, since they all edit the same repository.
+    const job = codeQueue.then(() => codeOne(index, tc, runDir, result))
+    codeQueue = job.catch(() => {})
+    await job
+  }
+
+  const codeOne = async (index: number, tc: TestCase, runDir: string, result: CaseResult) => {
+    if (opts.signal?.aborted) return
+    // A case that already has a test (from an earlier job): run it first. Passing, it needs no coding job at all;
+    // failing, the job updates it instead of writing a new one.
+    const mapped = readMappings(opts.repo!).cases[tc.id]
+    let existingTest: ExistingTest | undefined
+    if (mapped?.testFile && mapped.command && (mapped.status === "automated" || mapped.status === "known_defect") && existsSync(path.join(opts.repo!, mapped.testFile))) {
+      emit({ type: "case-event", index, case: tc, event: { type: "code", kind: "info", text: `${tc.id} already has a test, ${mapped.testFile}: ForgeQE runs it first` } })
+      const run = await (opts.runTest || runTestCommand)({ command: mapped.command, cwd: opts.repo!, timeoutSeconds: config.code.testTimeoutSeconds, signal: opts.signal, hide: privateEnvNames(config), save: path.join(runDir, "existing-test") })
+      const defectNow = result.failure?.type === "functional_defect"
+      // Reused as it is: a normal test that passes on a case that passes, or a known-defect test (an expected failure)
+      // on a case that still shows the defect.
+      const fits = mapped.status === "known_defect" ? defectNow : !defectNow
+      if (run.ok && fits) {
+        emit({ type: "case-event", index, case: tc, event: { type: "code", kind: "test", ok: true, attempt: 0, text: `${mapped.testFile} passes as it is: no new test needed` } })
+        result.code = { status: "passed", testFile: mapped.testFile, command: mapped.command, attempts: 0, existing: "reused", ...(mapped.testName ? { testName: mapped.testName } : {}), ...(mapped.status === "known_defect" ? { knownDefect: true } : {}) }
+        emit({ type: "code-done", index, case: tc, result })
+        return
+      }
+      if (opts.signal?.aborted) return
+      const why =
+        mapped.status === "known_defect" && !defectNow
+          ? `It is marked as an expected failure for a known defect${mapped.bug ? ` (${mapped.bug.label})` : ""}, and the browser run now passes: the defect looks fixed. Remove the expected-failure marker and keep the assertions.`
+          : defectNow && run.ok
+            ? "It passes, although this run found a functional defect (below): its assertions miss it. Assert the expected result the defect breaks, and mark the test as an expected failure."
+            : defectNow
+              ? "It fails because of the functional defect this run found (below): keep its assertions and mark it as an expected failure naming the defect."
+              : "It fails now: the application or the page changed since it was written."
+      existingTest = { testFile: mapped.testFile, command: mapped.command, output: run.output, why }
+    }
+    emit({ type: "code-start", index, case: tc })
+    let code: CodeResult | undefined
+    let error: string | undefined
+    try {
+      code = await coder({
+        config,
+        repo: opts.repo!,
+        runDir,
+        signal: opts.signal,
+        onEvent: (event) => emit({ type: "case-event", index, case: tc, event }),
+        testCase: tc,
+        ...(existingTest ? { existingTest } : {}),
+        ...(result.failure?.type === "functional_defect" ? { knownDefect: { reason: result.failure.reason, ...(result.bug ? { bug: result.bug } : {}) } } : {}),
+      })
+    } catch (err) {
+      error = (err as Error).message || String(err)
+      emit({ type: "case-event", index, case: tc, event: { type: "log", level: "error", text: `Coding agent: ${error}` } })
+    }
+    result.code = code
+      ? {
+          status: code.status,
+          testFile: code.testFile,
+          command: code.command,
+          attempts: code.attempts,
+          ...(code.handoff ? { handoff: code.handoff } : {}),
+          ...(code.skills?.length ? { skills: code.skills } : {}),
+          ...(code.testName ? { testName: code.testName } : {}),
+          ...(code.knownDefect ? { knownDefect: true } : {}),
+          ...(code.attention ? { attention: code.attention.dir } : {}),
+          ...(existingTest ? { existing: "updated" as const } : {}),
+        }
+      : { status: "failed", attempts: 0, ...(error ? { error } : {}) }
+    result.tokens += code ? code.usage.input + code.usage.output : 0
+    if (code) {
+      result.codeUsage = code.usage
+      result.codeCost = code.cost
+    }
+    // A passing test for an Azure DevOps test case is set as its Associated Automation.
+    if (code?.status === "passed" && code.testFile && tc.source === "ado" && (opts.writeBack ?? config.sources.writeBack)) {
+      const item = await associateAdoAutomation(config.sources, tc, { name: code.testName || `${tc.id} ${tc.title}`, file: code.testFile, command: code.command })
+      earlyBugs.push(item)
+      emit({ type: "writeback", item })
+    }
+    emit({ type: "code-done", index, case: tc, result })
+  }
+
+  let next = 0
+  const workers = Array.from({ length: Math.min(Math.max(1, opts.parallel || config.suite.parallel), total) }, async () => {
+    while (next < total && !opts.signal?.aborted) await runOne(next++)
+  })
+  await Promise.all(workers)
+
+  const finished = results.map((r, i): CaseResult => {
+    if (r) return r
+    const now = new Date().toISOString()
+    return { case: cases[i], status: "stopped", summary: "Not run: the suite was stopped.", startedAt: now, finishedAt: now, ms: 0, tokens: 0 }
+  })
+
+  const posted: WriteBack[] = []
+  if (opts.writeBack ?? config.sources.writeBack) {
+    const ran = finished.filter((r) => r.runDir)
+    const filed = new Set(earlyBugs.filter((b) => b.source === "bugs").map((b) => b.caseId))
+    posted.push(...earlyBugs)
+    for (const item of [...(await postResults(ran, config.sources, name)), ...(await fileBugs(ran.filter((r) => !filed.has(r.case.id)), config.sources, name))]) {
+      posted.push(item)
+      emit({ type: "writeback", item })
+    }
+  }
+
+  const finishedAt = new Date().toISOString()
+  const suite: Omit<SuiteResult, "files"> = {
+    name,
+    dir,
+    startedAt,
+    finishedAt,
+    ms: Date.now() - t0,
+    results: finished,
+    writeBack: posted,
+    stopped: Boolean(opts.signal?.aborted),
+    env: reportEnv(config, { url: opts.url, headed: opts.headed }),
+  }
+  return { ...suite, files: writeReports(suite) }
+}
+
+function timelineLines(runDir: string): CaseResult["steps"] | undefined {
+  const steps = readTimeline(runDir).flatMap((t) => t.actions.filter((a) => !a.done).map((a) => ({ text: a.error ? `${a.text}: ${a.error}` : a.text, ok: a.ok })))
+  return steps.length ? steps : undefined
+}
+
+/** 0 when every case passed (and every test written for it passes), 2 when stopped, otherwise 1. */
+export function suiteExitCode(s: Pick<SuiteResult, "results" | "stopped">): number {
+  if (s.stopped) return 2
+  const ok = s.results.every((r) => r.status === "passed" && (!r.code || r.code.status === "passed"))
+  return ok ? 0 : 1
+}

package/src/summary.ts

@@ -0,0 +1,188 @@
+import { qualityLine, type QualityReport } from "./quality/budgets.ts"
+import os from "node:os"
+import path from "node:path"
+
+import type { CodeResult, CodeStatus, MemoryInfo, RunStatus, Usage } from "./types.ts"
+import { usageLine, type Cost } from "./usage.ts"
+import type { Card } from "./card.ts"
+import { formatDuration, formatTokens } from "./tui/theme.ts"
+
+export type RunSummary = {
+  status: RunStatus
+  /** "Task complete", "Task failed", or "Test case failed" when an expected result did not hold. */
+  title: string
+  /** Expected results that did not hold: "Expected: … · the page shows: …". */
+  failed: string[]
+  /** The agent's own account of what it did and found, or the reason it stopped. */
+  text: string
+  finalUrl: string
+  stats: string
+  /** What page memory replayed and learned, e.g. "replayed all 4 steps · 1 LLM step · 3 elements on 1 page". */
+  memory: string
+  savedDir: string
+  savedFiles: string[]
+  /** Tokens (in, cached, out) and cost, e.g. "52.7K tokens (50.1K in, 31K of it cached · 2.6K out) · US$0.07". */
+  usage: string
+  /** WCAG rules passed and failed, Core Web Vitals, and whether the budgets held. */
+  quality?: string
+}
+
+export const STATUS_TITLE: Record<RunStatus, string> = {
+  complete: "Task complete",
+  fail: "Task failed",
+  stopped: "Run stopped",
+}
+
+export const STATUS_MARK: Record<RunStatus, string> = { complete: "✓", fail: "✗", stopped: "■" }
+
+/** Host and path without the query string: booking.com/searchresults.en-gb.html */
+export function shortUrl(url: string, max = 70): string {
+  if (!url || url === "about:blank") return ""
+  try {
+    const u = new URL(url)
+    const s = `${u.hostname.replace(/^www\./, "")}${u.pathname === "/" ? "" : u.pathname}`
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`
+  } catch {
+    return url.length <= max ? url : `${url.slice(0, max - 1)}…`
+  }
+}
+
+export function runStats(ms: number, tokens: number, steps: number): string {
+  return `${steps} ${steps === 1 ? "step" : "steps"} · ${formatDuration(ms)} · ${formatTokens(tokens)} tokens`
+}
+
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`
+
+export function memoryLine(m?: MemoryInfo): string {
+  if (!m) return ""
+  const parts: string[] = []
+  if (m.replayTotal) {
+    parts.push(m.replayed === m.replayTotal ? `replayed all ${m.replayed} steps` : `replayed ${m.replayed} of ${m.replayTotal} steps`)
+    parts.push(plural(m.llmSteps, "LLM step"))
+  }
+  if (m.elements) parts.push(`${plural(m.elements, "element")} on ${plural(m.pages, "page")}${m.newElements ? ` (${m.newElements} new)` : ""}`)
+  if (m.flow) parts.push(m.flow === "saved" ? "flow saved for replay" : "flow updated")
+  return parts.join(" · ")
+}
+
+export function buildSummary(opts: {
+  status: RunStatus
+  text: string
+  finalUrl: string
+  ms: number
+  tokens: number
+  steps: number
+  files: string[]
+  memory?: MemoryInfo
+  usage?: Usage
+  cost?: Cost
+  outcome?: "passed" | "assertion_failed" | "error"
+  failedChecks?: { expected: string; actual: string }[]
+  quality?: QualityReport
+  budgetExceeded?: string[]
+}): RunSummary {
+  const dir = opts.files.length ? path.relative(process.cwd(), path.dirname(opts.files[0])) || "." : ""
+  const assertion = opts.outcome === "assertion_failed"
+  // Steps that passed on a page over budget: the run fails on the budget.
+  const overBudget = opts.status === "complete" && Boolean(opts.budgetExceeded?.length)
+  return {
+    status: overBudget ? "fail" : opts.status,
+    title: assertion ? "Test case failed: expected result not met" : overBudget ? "Budget exceeded: the steps passed, a page is over budget" : STATUS_TITLE[opts.status],
+    failed: [...(assertion ? (opts.failedChecks || []).map((c) => `Expected: ${c.expected} · the page shows: ${c.actual}`) : []), ...(opts.budgetExceeded || []).map((b) => `Budget: ${b}`)],
+    text: opts.text.trim() || (opts.status === "complete" ? "Finished without a written result." : "No details were reported."),
+    finalUrl: shortUrl(opts.finalUrl),
+    stats: runStats(opts.ms, opts.tokens, opts.steps),
+    memory: memoryLine(opts.memory),
+    savedDir: dir,
+    savedFiles: opts.files.map((f) => path.basename(f)),
+    usage: opts.usage ? usageLine(opts.usage, opts.cost) : "",
+    ...(opts.quality && qualityLine(opts.quality) ? { quality: qualityLine(opts.quality) } : {}),
+  }
+}
+
+/** Plain-text block for `forgeqe run`. */
+export function formatSummary(s: RunSummary): string {
+  const lines = [`${STATUS_MARK[s.status]} ${s.title} · ${s.stats}`, "", ...(s.failed.length ? [...s.failed.map((f) => `✗ ${f}`), ""] : []), s.text, ""]
+  if (s.finalUrl) lines.push(`Ended on  ${s.finalUrl}`)
+  if (s.memory) lines.push(`Memory    ${s.memory}`)
+  if (s.quality) lines.push(`Quality   ${s.quality}`)
+  if (s.usage) lines.push(`Usage     ${s.usage}`)
+  if (s.savedDir) lines.push(`Saved     ${s.savedDir}/  ${s.savedFiles.join(" · ")}`)
+  return lines.join("\n")
+}
+
+export type CodeSummary = {
+  status: CodeStatus
+  stats: string
+  text: string
+  testFile: string
+  command: string
+  reused: string
+  changed: string
+  repo: string
+  browser: string
+  review: string
+  usage: string
+}
+
+export const CODE_TITLE: Record<CodeStatus, string> = {
+  passed: "Test passed",
+  failed: "Test not passing",
+  stopped: "Coding stopped",
+  blocked: "Test blocked by the app",
+}
+
+export const CODE_MARK: Record<CodeStatus, string> = { passed: "✓", failed: "✗", stopped: "■", blocked: "✗" }
+
+export function buildCodeSummary(r: CodeResult, ms: number): CodeSummary {
+  const attempts = `${r.attempts}/${r.maxAttempts} ${r.maxAttempts === 1 ? "attempt" : "attempts"}`
+  const text =
+    r.status === "passed"
+      ? r.notes || "ForgeQE ran the new test and it passed."
+      : r.status === "stopped"
+        ? "Stopped before the test passed."
+        : r.notes || (r.command ? "The test still fails when ForgeQE runs it." : "Scribe did not report a test to run.")
+  return {
+    status: r.status,
+    stats: `${attempts} · ${formatDuration(ms)} · ${formatTokens(r.usage.input + r.usage.output)} tokens · ${r.model || "Scribe"}`,
+    text,
+    testFile: r.testFile || "",
+    command: r.command || "",
+    reused: r.reused.join(", "),
+    changed: r.changed.join(", "),
+    repo: shortPath(r.repo),
+    browser: (r.browsers || []).join(", "),
+    review: r.review
+      ? r.review.standardsLeft
+        ? `approved: it tests the goal; coding standards still to fix: ${r.review.issues.filter((i) => i.kind === "standards").map((i) => i.problem).join(" ")}`
+        : `${r.review.approved ? "approved" : `not approved, ${r.review.issues.length} ${r.review.issues.length === 1 ? "issue" : "issues"}`}: ${r.review.summary}`
+      : "",
+    usage: usageLine(r.usage, r.cost),
+  }
+}
+
+/** A path as the user reads it: relative inside the working directory, otherwise ~/… or absolute. */
+export function shortPath(dir: string): string {
+  const rel = path.relative(process.cwd(), dir)
+  if (!rel) return "."
+  if (!rel.startsWith("..") && !path.isAbsolute(rel)) return rel
+  const home = os.homedir()
+  return dir === home || dir.startsWith(home + path.sep) ? "~" + dir.slice(home.length) : dir
+}
+
+export function formatCodeSummary(s: CodeSummary): string {
+  const lines = [`${CODE_MARK[s.status]} ${CODE_TITLE[s.status]} · ${s.stats}`, "", s.text, ""]
+  if (s.testFile) lines.push(`Test      ${s.testFile}  (in ${s.repo})`)
+  if (s.command) lines.push(`Command   ${s.command}`)
+  if (s.reused) lines.push(`Reused    ${s.reused}`)
+  if (s.changed) lines.push(`Changed   ${s.changed}`)
+  if (s.browser) lines.push(`Browser   ${s.browser}`)
+  if (s.review) lines.push(`Review    ${s.review}`)
+  if (s.usage) lines.push(`Usage     ${s.usage}`)
+  return lines.join("\n")
+}
+
+export function codeCard(s: CodeSummary): Card {
+  const [, , ...body] = formatCodeSummary(s).split("\n")
+  return { status: s.status === "passed" ? "ok" : s.status === "stopped" ? "stopped" : "fail", title: CODE_TITLE[s.status], stats: s.stats, body }
+}

package/src/tools.ts

@@ -0,0 +1,130 @@
+import { spawnSync } from "node:child_process"
+import { createHash } from "node:crypto"
+import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+export type Log = (text: string) => void
+
+export const WINDOWS = process.platform === "win32"
+export const EXE = WINDOWS ? ".exe" : ""
+
+/** ForgeQE was called WebPilot: a folder that exists only under the old name is still used, so earlier setups keep working. */
+export function renamed(dir: string, name: string, legacy: string): string {
+  const now = path.join(dir, name)
+  const old = path.join(dir, legacy)
+  return !existsSync(now) && existsSync(old) ? old : now
+}
+
+export function forgeqeHome(): string {
+  return process.env.FORGEQE_HOME || renamed(os.homedir(), ".forgeqe", ".webpilot")
+}
+
+/** A project's ForgeQE folder next to forgeqe.yaml: .forgeqe, or .webpilot from before the rename. */
+export function projectDir(base: string): string {
+  return renamed(base, ".forgeqe", ".webpilot")
+}
+
+/** Where ForgeQE keeps the programs it downloads: <name>-<version>/<binary>. */
+export function toolsDir(): string {
+  return path.join(forgeqeHome(), "tools")
+}
+
+export function toolPath(name: string, version: string, binary: string): string {
+  return path.join(toolsDir(), `${name}-${version}`, binary)
+}
+
+export function isMusl(): boolean {
+  if (process.platform !== "linux") return false
+  try {
+    return readdirSync("/lib").some((f) => f.startsWith("ld-musl-"))
+  } catch {
+    return false
+  }
+}
+
+/** Windows ships bsdtar (reads zip) in System32; a Git-for-Windows GNU tar earlier on PATH cannot. macOS tar reads zip too. */
+function tarCommand(): string {
+  const system = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "tar.exe")
+  return WINDOWS && existsSync(system) ? system : "tar"
+}
+
+function findFile(dir: string, name: string): string | null {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isFile() && entry.name === name) return full
+    if (entry.isDirectory()) {
+      const found = findFile(full, name)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+export async function fetchBytes(url: string, headers?: Record<string, string>): Promise<Buffer> {
+  const res = await fetch(url, { redirect: "follow", headers })
+  if (!res.ok) throw new Error(`${url} returned ${res.status}`)
+  return Buffer.from(await res.arrayBuffer())
+}
+
+/** SHA-256 GitHub records for a release asset, or null when the API does not answer (rate limit, proxy). */
+export async function githubDigest(repo: string, tag: string, asset: string): Promise<string | null> {
+  try {
+    const body = await fetchBytes(`https://api.github.com/repos/${repo}/releases/tags/${tag}`, { Accept: "application/vnd.github+json" })
+    const found = (JSON.parse(body.toString("utf8")).assets || []).find((a: { name: string }) => a.name === asset)
+    const digest = String(found?.digest || "")
+    return digest.startsWith("sha256:") ? digest.slice(7).toLowerCase() : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Download a release archive (zip or tar.gz), check its SHA-256 when one is known, and put `binary` at
+ * ~/.forgeqe/tools/<name>-<version>/<binary>. Older versions of the same tool are removed.
+ * No admin rights, PATH or shell profile changes.
+ */
+export async function installTool(opts: {
+  name: string
+  version: string
+  asset: string
+  url: string
+  binary: string
+  sha256: string | null
+  log: Log
+  /** How the logs name the tool; default: name, version, and asset. */
+  label?: string
+}): Promise<string> {
+  const { name, version, asset, binary, log } = opts
+  const label = opts.label || `${name} ${version} (${asset})`
+  log(`Downloading ${label} into ${toolsDir()} (one time).`)
+  const archive = await fetchBytes(opts.url)
+  if (opts.sha256) {
+    if (createHash("sha256").update(archive).digest("hex") !== opts.sha256) throw new Error(`checksum mismatch for ${opts.label || asset}`)
+  } else {
+    log(`No published checksum for ${opts.label || asset} could be fetched; relying on the HTTPS download.`)
+  }
+
+  const work = path.join(toolsDir(), `.${name}-${process.pid}`)
+  rmSync(work, { recursive: true, force: true })
+  mkdirSync(work, { recursive: true })
+  try {
+    const file = path.join(work, asset)
+    writeFileSync(file, archive)
+    const r = spawnSync(tarCommand(), ["-xf", file, "-C", work], { encoding: "utf8" })
+    if (r.error || r.status !== 0) throw new Error(`could not unpack ${asset}: ${r.error?.message || r.stderr}`)
+    const found = findFile(work, binary)
+    if (!found) throw new Error(`${binary} not found in ${asset}`)
+    const target = toolPath(name, version, binary)
+    rmSync(path.dirname(target), { recursive: true, force: true })
+    mkdirSync(path.dirname(target), { recursive: true })
+    renameSync(found, target)
+    if (!WINDOWS) chmodSync(target, 0o755)
+    for (const old of readdirSync(toolsDir())) {
+      if (old.startsWith(`${name}-`) && old !== `${name}-${version}`) rmSync(path.join(toolsDir(), old), { recursive: true, force: true })
+    }
+    return target
+  } finally {
+    rmSync(work, { recursive: true, force: true })
+  }
+}