@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/init.ts

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process"
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { forgeqeHome, projectDir } from "./tools.ts"
+
+import { userConfigDir } from "./config.ts"
+import { KNOWLEDGE_TEMPLATES } from "./knowledge.ts"
+import { copyManaged } from "./managed.ts"
+import { PROMPTS_DIR } from "./prompts.ts"
+import { PREBUILT_DIR } from "./skills/registry.ts"
+
+const ROOT = path.resolve(import.meta.dir, "..")
+
+export function initWorkspace(
+  directory: string,
+  opts: { force?: boolean; profile?: string },
+): { created: string[]; notes: string[] } {
+  mkdirSync(directory, { recursive: true })
+  const created: string[] = []
+  const notes: string[] = []
+  const profile = opts.profile
+
+  const pairs: Array<[string, string, (body: string) => string]> = [
+    ["llms.example.json", "llms.json", (body) => body],
+    [
+      "forgeqe.example.yaml",
+      "forgeqe.yaml",
+      (body) => (profile ? body.replace(/^ {2}# active: .*$/m, `  active: ${profile}`) : body),
+    ],
+  ]
+
+  const globalModels = path.join(userConfigDir(), "llms.json")
+  for (const [srcName, destName, map] of pairs) {
+    const src = path.join(ROOT, srcName)
+    const dest = path.join(directory, destName)
+    if (destName === "llms.json" && !existsSync(dest) && existsSync(globalModels) && path.resolve(directory) !== userConfigDir()) {
+      notes.push(`Using your profiles from ${globalModels}; no project llms.json written.`)
+      continue
+    }
+    if (!existsSync(src)) {
+      notes.push(`Template missing: ${src}`)
+      continue
+    }
+    if (existsSync(dest) && !opts.force) {
+      notes.push(`Kept existing ${dest}`)
+      continue
+    }
+    if (destName === "forgeqe.yaml") {
+      writeFileSync(dest, map(readFileSync(src, "utf8")), "utf8")
+    } else {
+      writeFileSync(dest, map(readFileSync(src, "utf8")), "utf8")
+    }
+    created.push(dest)
+  }
+
+  const home = path.resolve(directory) === userConfigDir()
+  if (!home) {
+    const ignored = ignoreReports(directory)
+    if (ignored) notes.push(ignored)
+  }
+
+  // Prompts, skills, and product knowledge templates, to read and change: .forgeqe/ in a project, ~/.forgeqe for the user.
+  const root = home ? forgeqeHome() : projectDir(directory)
+  const shown = (p: string) => (home ? p : path.relative(directory, p) || p)
+  for (const { what, src, dest, keys } of [
+    { what: "prompts", src: PROMPTS_DIR, dest: path.join(root, "prompts"), keys: entries(PROMPTS_DIR, (e) => e.endsWith(".md")) },
+    { what: "skills", src: PREBUILT_DIR, dest: path.join(root, "skills"), keys: entries(PREBUILT_DIR, (e) => existsSync(path.join(PREBUILT_DIR, e, "SKILL.md"))) },
+    { what: "product knowledge templates", src: KNOWLEDGE_TEMPLATES, dest: path.join(root, "knowledge"), keys: entries(KNOWLEDGE_TEMPLATES, (e) => /\.(md|txt)$/.test(e)) },
+  ]) {
+    const { copied, kept } = copyManaged(src, dest, keys, { force: opts.force })
+    if (copied.length) created.push(`${dest}/ (${copied.length} ${what})`)
+    if (kept.length) notes.push(`Kept ${kept.length} existing ${what} in ${shown(dest)}${opts.force ? " (edited ones are never overwritten)" : ""}`)
+  }
+
+  const known = ["azure-gpt4o", "azure-gpt4o-entra", "openai-gpt4o", "ollama-llama", "compatible"]
+  if (profile && !known.includes(profile)) {
+    notes.push(`Profile "${profile}" is not in the template llms.json. Add it before running.`)
+  }
+  return { created, notes }
+}
+
+function entries(dir: string, keep: (name: string) => boolean): string[] {
+  try {
+    return readdirSync(dir).filter((e) => !e.startsWith(".") && keep(e)).sort()
+  } catch {
+    return []
+  }
+}
+
+/** Adds .forgeqe/reports/ (.webpilot/reports/ in a project from before the rename) to the folder's .gitignore unless git already ignores it; the note to show, or null. */
+export function ignoreReports(directory: string): string | null {
+  const REPORTS_IGNORE = `${path.basename(projectDir(directory))}/reports/`
+  const check = spawnSync("git", ["check-ignore", "-q", `${REPORTS_IGNORE}run`], { cwd: directory, stdio: "ignore" })
+  if (check.status === 0) return null
+  const file = path.join(directory, ".gitignore")
+  const body = existsSync(file) ? readFileSync(file, "utf8") : ""
+  if (body.split(/\r?\n/).some((l) => l.trim() === REPORTS_IGNORE)) return null
+  appendFileSync(file, `${body && !body.endsWith("\n") ? "\n" : ""}${body ? "\n" : ""}# ForgeQE run reports (steps, screenshots, traces)\n${REPORTS_IGNORE}\n`)
+  return `Added ${REPORTS_IGNORE} to ${file}`
+}

package/src/knowledge.ts

@@ -0,0 +1,114 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+import { copyState, MANIFEST } from "./managed.ts"
+
+/**
+ * Product knowledge: markdown or text files in .forgeqe/knowledge/ (knowledge.dir) about the product: what it does,
+ * roles, glossary, business rules, test data, environments. ForgeQE's agent sees the list and reads what a request
+ * needs; planners and the browser agent get the sections that match their task. A template copy nobody filled in
+ * (unchanged since forgeqe init) is left out.
+ */
+
+export const KNOWLEDGE_TEMPLATES = path.resolve(import.meta.dir, "..", "knowledge")
+const MAX_FILE = 200_000
+const STOP = new Set(
+  "the a an and or of to in on for with is are be should must can will user users when then that this from into able page shown show shows display displayed after before your their there what which while about have has not".split(" "),
+)
+
+export type KnowledgeFile = { file: string; rel: string; title: string; text: string }
+export type Section = { rel: string; heading: string; text: string }
+
+function walk(dir: string, at = ""): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(path.join(dir, at))
+  } catch {
+    return []
+  }
+  const out: string[] = []
+  for (const e of entries.sort()) {
+    if (e.startsWith(".") || e === MANIFEST) continue
+    const rel = path.join(at, e)
+    const full = path.join(dir, rel)
+    if (statSync(full).isDirectory()) out.push(...walk(dir, rel))
+    else if (/\.(md|txt)$/i.test(e) && e.toLowerCase() !== "readme.md") out.push(rel)
+  }
+  return out
+}
+
+/** The knowledge files that have content of their own (not an untouched template). */
+export function readKnowledge(dir: string | undefined): KnowledgeFile[] {
+  if (!dir || !existsSync(dir)) return []
+  return walk(dir)
+    .filter((rel) => copyState(dir, rel) !== "unchanged" && statSync(path.join(dir, rel)).size <= MAX_FILE)
+    .map((rel) => {
+      const text = readFileSync(path.join(dir, rel), "utf8").replace(/<!--[\s\S]*?-->/g, "").trim()
+      const title = text.match(/^#\s+(.+)$/m)?.[1]?.trim() || rel.replace(/\.(md|txt)$/i, "")
+      return { file: path.join(dir, rel), rel: rel.split(path.sep).join("/"), title, text }
+    })
+    .filter((k) => k.text.replace(/^#.*$/gm, "").trim().length > 0)
+}
+
+/** Each file split at its ## (or deeper) headings, so a task gets only the parts it needs. */
+export function sections(files: KnowledgeFile[]): Section[] {
+  const out: Section[] = []
+  for (const f of files) {
+    const parts = f.text.split(/\n(?=#{2,4}\s)/)
+    for (const p of parts) {
+      const heading = p.match(/^#{1,4}\s+(.+)$/m)?.[1]?.trim() || f.title
+      const text = p.trim()
+      if (text.replace(/^#.*$/gm, "").trim()) out.push({ rel: f.rel, heading: heading === f.title ? f.title : `${f.title} › ${heading}`, text })
+    }
+  }
+  return out
+}
+
+/** A word without its plural or past ending, so "addresses" matches "address" and "refused" matches "refuse". */
+function stem(w: string): string {
+  if (w.endsWith("sses")) return w.slice(0, -2)
+  if (w.endsWith("ies") && w.length > 4) return `${w.slice(0, -3)}y`
+  if (w.endsWith("ing") && w.length > 5) return w.slice(0, -3)
+  if (w.endsWith("ed") && w.length > 4) return w.slice(0, -2)
+  if (w.endsWith("s") && !w.endsWith("ss") && w.length > 4) return w.slice(0, -1)
+  return w
+}
+
+const words = (s: string) => new Set(s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 4 && !STOP.has(w)).map(stem))
+
+/**
+ * The sections that share the most words with the task, most relevant first, up to `maxChars`. `minHits` leaves out
+ * sections that share fewer words (the browser agent asks for 2, so only clearly related parts reach every step).
+ */
+export function relevantKnowledge(files: KnowledgeFile[], task: string, maxChars: number, minHits = 1): Section[] {
+  const want = words(task)
+  if (!want.size || maxChars <= 0) return []
+  const scored = sections(files)
+    .map((s) => {
+      const have = words(`${s.heading} ${s.text}`)
+      let hits = 0
+      for (const w of want) if (have.has(w)) hits++
+      return { s, hits }
+    })
+    .filter((x) => x.hits >= minHits)
+    .sort((a, b) => b.hits - a.hits)
+  const out: Section[] = []
+  let used = 0
+  for (const { s } of scored) {
+    if (used + s.text.length > maxChars) continue
+    out.push(s)
+    used += s.text.length
+  }
+  return out
+}
+
+/** Sections as a prompt block, or "" when there are none. */
+export function knowledgeBlock(found: Section[], title = "Product knowledge"): string {
+  if (!found.length) return ""
+  return [`## ${title}`, "", "From the team's notes about the product (.forgeqe/knowledge). Use them where they apply; the live application wins where they disagree.", "", ...found.map((s) => `### ${s.heading} (${s.rel})\n${s.text.replace(/^#{1,4}\s+.*\n?/, "").trim()}`)].join("\n")
+}
+
+/** One line per file, for ForgeQE's agent to pick what to read. */
+export function knowledgeIndex(files: KnowledgeFile[]): string[] {
+  return files.map((f) => `- ${f.file}: ${f.title} (${Math.max(1, Math.round(f.text.length / 1000))} KB)`)
+}

package/src/legacyEnv.ts

@@ -0,0 +1,9 @@
+/**
+ * ForgeQE was called WebPilot: each WEBPILOT_* variable still works as its FORGEQE_* name, which wins when both are set.
+ * The entry point imports this first, before anything reads the environment.
+ */
+for (const [key, value] of Object.entries(process.env)) {
+  if (!key.startsWith("WEBPILOT_") || value === undefined) continue
+  const name = `FORGEQE_${key.slice("WEBPILOT_".length)}`
+  if (process.env[name] === undefined) process.env[name] = value
+}

package/src/llm.ts

@@ -0,0 +1,61 @@
+import type { Price } from "./usage.ts"
+
+/**
+ * One entry of llms.json, driven by the ForgeQE engine. `none` stands in when no profile is set up;
+ * `mock` is the offline test double, chosen only with --profile mock or WP_LLM_PROFILE=mock.
+ */
+export type LlmProfile = {
+  provider: "none" | "mock" | "openai" | "azure" | "ollama" | "openai_compatible"
+  model: string
+  endpoint?: string
+  deployment?: string
+  apiKey?: string
+  apiKeyEnv?: string
+  /** How ForgeQE signs in to the model: an API key (the default), or Microsoft Entra ID with no key at all. */
+  auth?: "key" | "entra"
+  /** auth: entra — the client id of the user-assigned managed identity to use; else the machine's default identity. */
+  managedIdentityClientId?: string
+  /** auth: entra — the token's scope; default Azure OpenAI's. A gateway such as API Management may want its own. */
+  tokenScope?: string
+  apiVersion?: string
+  temperature?: number
+  /** Price per million tokens, for the cost shown in reports: llms.json's, else the model's list price. */
+  price?: Price
+  /** llms.json's price differs from the model's list price: what to tell the user. */
+  priceWarning?: string
+}
+
+/**
+ * Why this profile has no API key in this environment, or null. Checked before any request, so a missing key
+ * names its variable instead of coming back as the provider's "access denied".
+ */
+export const NO_MODEL_SET_UP =
+  "No model is set up yet. Add a profile with your provider and key to llms.json (forgeqe init writes one to fill in), " +
+  "then pick it with llm.active in forgeqe.yaml or Tab in the shell. forgeqe models lists the profiles ForgeQE sees."
+
+/** Why ForgeQE's agent or the coding agent has no model to run on (code.model can supply one), or null. */
+export function noAgentModel(p: LlmProfile, codeModel: string | undefined, what: string): string | null {
+  if (codeModel) return null
+  if (p.provider === "none") return NO_MODEL_SET_UP
+  if (p.provider === "mock") return `The mock profile has no model for ${what}. Pick a live profile, or set code.model.`
+  return null
+}
+
+/** The providers that can sign in with Microsoft Entra ID instead of a key. */
+export const ENTRA_PROVIDERS: LlmProfile["provider"][] = ["azure", "openai_compatible"]
+
+export function missingKey(p: LlmProfile): string | null {
+  if (p.provider === "none") return NO_MODEL_SET_UP
+  if (p.auth === "entra") {
+    // The credential is found when the first request is made: managed identity, workload identity or az login.
+    return ENTRA_PROVIDERS.includes(p.provider) ? null : `auth: entra works with the azure and openai_compatible providers, not ${p.provider} (profile for ${p.model}).`
+  }
+  if (p.provider !== "azure" && p.provider !== "openai") return null
+  if (p.apiKey?.trim()) return null
+  if (!p.apiKeyEnv) return `The ${p.provider} profile for ${p.model} has no api_key_env in llms.json, so it has no API key.`
+  if (process.env[p.apiKeyEnv]?.trim()) return null
+  return (
+    `The ${p.provider} profile for ${p.model} reads its API key from ${p.apiKeyEnv}, which is not set in this terminal. ` +
+    `Set ${p.apiKeyEnv} (or put it in a .env file next to forgeqe.yaml), or change api_key_env in llms.json to the variable that holds your key.`
+  )
+}

package/src/locale.ts

@@ -0,0 +1,25 @@
+import { execFileSync } from "node:child_process"
+
+function envLocale(): string | undefined {
+  const raw = process.env.LC_ALL || process.env.LC_MONETARY || process.env.LANG || ""
+  if (!raw || raw === "C" || raw === "POSIX" || raw.startsWith("C.")) return undefined
+  return raw.split(".")[0].replaceAll("_", "-")
+}
+
+let cached: string | undefined
+
+/** The language this machine is set to. A C/POSIX shell locale is ignored. */
+export function systemLocale(): string {
+  if (cached) return cached
+  const fromEnv = envLocale()
+  if (fromEnv) return (cached = fromEnv)
+  if (process.platform === "darwin") {
+    try {
+      const apple = execFileSync("defaults", ["read", "-g", "AppleLocale"], { encoding: "utf8" }).trim()
+      if (apple) return (cached = apple.replaceAll("_", "-"))
+    } catch {
+      /* defaults is missing */
+    }
+  }
+  return (cached = Intl.DateTimeFormat().resolvedOptions().locale || "en-US")
+}

package/src/logins.ts

@@ -0,0 +1,148 @@
+import { spawn } from "node:child_process"
+import { existsSync, rmSync, statSync } from "node:fs"
+import { createInterface } from "node:readline"
+
+import { loginEnvNames } from "./childEnv.ts"
+import type { AppConfig, LoginConfig } from "./config.ts"
+import { loginPayload } from "./engine/bridge.ts"
+import { engineEnv, ensureEngine } from "./engine/setup.ts"
+
+export const LOGINS_USAGE = `Saved logins come from logins: in forgeqe.yaml, for example
+  logins:
+    shop:
+      url: https://staging.shop.example/login   # the site it signs in to (or domains: [...])
+      username_env: SHOP_USER
+      password_env: SHOP_PASSWORD
+      totp_env: SHOP_TOTP_SECRET                # optional: the authenticator secret (base32)
+
+  forgeqe login <name> [--url URL]   sign in once by hand in a browser window; the session is reused by runs
+  forgeqe logins                     list logins and their saved sessions
+  forgeqe logins clear <name|--all>  forget saved sessions`
+
+/** Where `forgeqe login` opens the browser: --url, the login's url, or its first domain without wildcards. */
+export function loginStartUrl(login: LoginConfig, url?: string): string {
+  const pick = url || login.url || login.domains.find((d) => !d.includes("*"))
+  if (!pick) throw new Error(`Login "${login.name}" has only wildcard domains; pass --url or set url: in forgeqe.yaml.`)
+  return /^[a-z]+:\/\//i.test(pick) ? pick : `https://${pick}`
+}
+
+export function describeLogins(cfg: AppConfig): string {
+  if (!cfg.logins.length) return `No saved logins.\n\n${LOGINS_USAGE}`
+  const lines = cfg.logins.map((l) => {
+    const envs = [l.usernameEnv, l.passwordEnv, l.totpEnv].filter((e): e is string => Boolean(e))
+    const missing = envs.filter((e) => !process.env[e])
+    const session = !l.sessionFile ? "not saved (save_session: false)" : existsSync(l.sessionFile) ? `saved ${statSync(l.sessionFile).mtime.toISOString().slice(0, 16).replace("T", " ")}` : "none yet"
+    return [
+      `${l.name}  ${l.domains.join(", ")}`,
+      `  credentials  ${envs.length ? envs.join(", ") : "none (session only)"}${missing.length ? `  (not set: ${missing.join(", ")})` : ""}`,
+      `  session      ${session}${l.sessionFile ? `  ${l.sessionFile}` : ""}`,
+    ].join("\n")
+  })
+  return lines.join("\n\n")
+}
+
+export function clearLogins(cfg: AppConfig, name: string | undefined, all: boolean): string {
+  const picked = all ? cfg.logins : cfg.logins.filter((l) => l.name === name)
+  if (!picked.length) throw new Error(name ? `No login "${name}" in forgeqe.yaml.` : "Name a login, or pass --all.")
+  const removed = picked.filter((l) => l.sessionFile && existsSync(l.sessionFile))
+  for (const l of removed) rmSync(l.sessionFile!, { force: true })
+  return removed.length ? `Forgot the saved session for ${removed.map((l) => l.name).join(", ")}.` : "No saved sessions to forget."
+}
+
+export type SignInResult = { status: "saved" | "cancelled" | "failed"; text: string; sessionFile?: string }
+
+/**
+ * Open a visible browser on the login's page with any saved session, let the user sign in (SSO, captcha, security
+ * keys: whatever the site asks), and save cookies and local storage once `wait` resolves true (false cancels).
+ */
+export async function signIn(
+  cfg: AppConfig,
+  name: string | undefined,
+  io: { url?: string; log?: (text: string) => void; wait: (prompt: string) => Promise<boolean>; signal?: AbortSignal },
+): Promise<SignInResult> {
+  const login = cfg.logins.find((l) => l.name === name)
+  if (!login) throw new Error(`${name ? `No login "${name}" in forgeqe.yaml.` : "Name the login to sign in to."}\n\n${LOGINS_USAGE}`)
+  if (!login.sessionFile) throw new Error(`Login "${login.name}" has save_session: false, so there is nowhere to keep the session.`)
+  const log = io.log || (() => {})
+  const start = loginStartUrl(login, io.url)
+  const python = await ensureEngine(log)
+  const child = spawn(python, ["-m", "forgeqe_engine", "login"], { env: engineEnv(undefined, loginEnvNames([login])), stdio: ["pipe", "pipe", "pipe"] })
+  const stderrTail: string[] = []
+  child.stderr.setEncoding("utf8")
+  child.stderr.on("data", (chunk: string) => {
+    stderrTail.push(...chunk.split("\n").filter(Boolean))
+    stderrTail.splice(0, Math.max(0, stderrTail.length - 20))
+  })
+  child.stdin.write(`${JSON.stringify({ url: start, logins: loginPayload([login]), overlay: cfg.browser.overlay })}\n`)
+
+  const send = (cmd: string) => {
+    if (!child.stdin.destroyed) child.stdin.write(`${cmd}\n`)
+  }
+  let interrupted = false
+  const onAbort = () => {
+    interrupted = true
+    send("stop")
+  }
+  io.signal?.addEventListener("abort", onAbort, { once: true })
+
+  let result: { success?: boolean; error?: string; summary?: string } | undefined
+  const events = createInterface({ input: child.stdout })
+  events.on("line", (line) => {
+    let e: { type?: string; text?: string; result?: typeof result }
+    try {
+      e = JSON.parse(line)
+    } catch {
+      return
+    }
+    if (e.type === "log" && e.text) {
+      log(e.text)
+      if (e.text.startsWith("Browser open")) {
+        void io.wait(`Sign in to ${login.name} in the browser window, then save the session.`).then((ok) => {
+          if (!ok) interrupted = true
+          send(ok ? "save" : "stop")
+        })
+      }
+    } else if (e.type === "done") result = e.result
+  })
+  const code = await new Promise<number | null>((resolve) => child.on("close", resolve))
+  io.signal?.removeEventListener("abort", onAbort)
+  if (result?.success) {
+    return {
+      status: "saved",
+      sessionFile: login.sessionFile,
+      text: `${result.summary}: ${login.sessionFile}\nRuns on these domains start signed in. The file holds your session cookies; keep it out of git.`,
+    }
+  }
+  if (result?.error === "cancelled" || (!result && interrupted)) return { status: "cancelled", text: "Cancelled; nothing was saved." }
+  return { status: "failed", text: result?.error || `The browser exited (${code}).${stderrTail.length ? `\n${stderrTail.slice(-8).join("\n")}` : ""}` }
+}
+
+/** `forgeqe login <name>`: sign in by hand, pressing Enter in the terminal to save (Ctrl+C cancels). */
+export async function interactiveLogin(cfg: AppConfig, name: string | undefined, url?: string): Promise<number> {
+  const keys = createInterface({ input: process.stdin })
+  const controller = new AbortController()
+  const onSigint = () => controller.abort()
+  process.on("SIGINT", onSigint)
+  try {
+    const r = await signIn(cfg, name, {
+      url,
+      signal: controller.signal,
+      log: (text) => console.log(text),
+      wait: (prompt) =>
+        new Promise((resolve) => {
+          console.log(`${prompt} Press Enter here to save (Ctrl+C cancels).`)
+          keys.once("line", () => resolve(true))
+          controller.signal.addEventListener("abort", () => resolve(false), { once: true })
+        }),
+    })
+    if (r.status === "failed") console.error(r.text)
+    else console.log(r.text)
+    return r.status === "saved" ? 0 : r.status === "cancelled" ? 2 : 1
+  } catch (err) {
+    console.error((err as Error).message)
+    return 1
+  } finally {
+    process.off("SIGINT", onSigint)
+    keys.close()
+  }
+}

package/src/managed.ts

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto"
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+/**
+ * Copies ForgeQE puts into a project (prompts, skills, product knowledge templates) and a manifest of what each
+ * looked like when copied. A copy nobody changed is still ForgeQE's: the built-in one is used, so it keeps getting
+ * ForgeQE's improvements. A copy someone edited is theirs and wins; when the built-in changed after the copy was made,
+ * it is reported as based on an older version.
+ */
+
+export const MANIFEST = ".forgeqe-manifest.json"
+/** The manifest's name before ForgeQE was renamed from WebPilot; still read. */
+const LEGACY_MANIFEST = ".webpilot-manifest.json"
+
+type Entry = { sha: string; at: string }
+type Manifest = { version: 1; note: string; entries: Record<string, Entry> }
+
+const NOTE = "Written by forgeqe init: the hash of each file or folder as it was copied. A copy you have not changed follows ForgeQE's built-in version; once you edit it, yours is used. Keep this file."
+
+export const sha = (data: string | Buffer) => createHash("sha256").update(data).digest("hex").slice(0, 16)
+
+function files(dir: string, at = ""): string[] {
+  const out: string[] = []
+  for (const e of readdirSync(path.join(dir, at)).sort()) {
+    if (e === MANIFEST || e === LEGACY_MANIFEST || e.startsWith(".")) continue
+    const rel = path.join(at, e)
+    if (statSync(path.join(dir, rel)).isDirectory()) out.push(...files(dir, rel))
+    else out.push(rel)
+  }
+  return out
+}
+
+/** A file's hash, or a folder's (every file in it, by relative path and content). */
+export function hashOf(p: string): string {
+  if (!existsSync(p)) return ""
+  if (!statSync(p).isDirectory()) return sha(readFileSync(p).toString("utf8").replace(/\r\n/g, "\n"))
+  return sha(files(p).map((f) => `${f.split(path.sep).join("/")}\n${readFileSync(path.join(p, f)).toString("utf8").replace(/\r\n/g, "\n")}`).join("\n\0"))
+}
+
+export function readManifest(dir: string): Manifest {
+  try {
+    const file = existsSync(path.join(dir, MANIFEST)) ? MANIFEST : LEGACY_MANIFEST
+    const m = JSON.parse(readFileSync(path.join(dir, file), "utf8")) as Manifest
+    return { version: 1, note: NOTE, entries: m?.entries && typeof m.entries === "object" ? m.entries : {} }
+  } catch {
+    return { version: 1, note: NOTE, entries: {} }
+  }
+}
+
+/** How a copy in `dir` stands: missing, unchanged since it was copied (ForgeQE's), or edited (the user's). */
+export function copyState(dir: string, key: string): "missing" | "unchanged" | "edited" | "own" {
+  const p = path.join(dir, key)
+  if (!existsSync(p)) return "missing"
+  const entry = readManifest(dir).entries[key]
+  if (!entry) return "own"
+  return hashOf(p) === entry.sha ? "unchanged" : "edited"
+}
+
+/** An edited copy whose built-in changed after it was copied: the user's version is based on an older one. */
+export function basedOnOlder(dir: string, key: string, builtin: string): boolean {
+  const entry = readManifest(dir).entries[key]
+  return Boolean(entry) && copyState(dir, key) === "edited" && hashOf(builtin) !== entry.sha
+}
+
+function copyTree(src: string, dest: string): void {
+  if (!statSync(src).isDirectory()) {
+    mkdirSync(path.dirname(dest), { recursive: true })
+    copyFileSync(src, dest)
+    return
+  }
+  for (const f of files(src)) {
+    mkdirSync(path.dirname(path.join(dest, f)), { recursive: true })
+    copyFileSync(path.join(src, f), path.join(dest, f))
+  }
+}
+
+/**
+ * Copy each of `keys` (files or folders under `srcRoot`) into `destRoot`, and record them in its manifest. What is
+ * already there is kept unless `force`, and then only when it is an unchanged copy: an edited one is never overwritten.
+ */
+export function copyManaged(srcRoot: string, destRoot: string, keys: string[], opts: { force?: boolean } = {}): { copied: string[]; kept: string[] } {
+  mkdirSync(destRoot, { recursive: true })
+  const m = readManifest(destRoot)
+  const copied: string[] = []
+  const kept: string[] = []
+  for (const key of keys) {
+    const src = path.join(srcRoot, key)
+    if (!existsSync(src)) continue
+    const state = copyState(destRoot, key)
+    if (state !== "missing" && !(opts.force && state === "unchanged")) {
+      kept.push(key)
+      continue
+    }
+    copyTree(src, path.join(destRoot, key))
+    m.entries[key] = { sha: hashOf(src), at: new Date().toISOString() }
+    copied.push(key)
+  }
+  if (copied.length) writeFileSync(path.join(destRoot, MANIFEST), `${JSON.stringify({ version: 1, note: NOTE, entries: Object.fromEntries(Object.entries(m.entries).sort(([a], [b]) => a.localeCompare(b))) }, null, 2)}\n`)
+  return { copied, kept }
+}