@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/skills/registry.ts

@@ -0,0 +1,217 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmdirSync, statSync, symlinkSync, unlinkSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { projectDir } from "../tools.ts"
+
+import YAML from "yaml"
+
+import type { SkillsConfig } from "../config.ts"
+import { copyState } from "../managed.ts"
+
+/** Who reads a skill: ForgeQE's agent, Scribe (writing, healing, finding, reviewing tests), or the browser agent. */
+export type SkillAgent = "forgeqe" | "scribe" | "browser"
+export const SKILL_AGENTS: SkillAgent[] = ["forgeqe", "scribe", "browser"]
+const DEFAULT_AGENTS: SkillAgent[] = ["forgeqe", "scribe"]
+
+/** In precedence order, lowest first: a later source replaces an earlier skill of the same name. */
+export type SkillSource = "prebuilt" | "external" | "user" | "project" | "extra"
+
+export type Skill = {
+  name: string
+  description: string
+  agents: SkillAgent[]
+  source: SkillSource
+  /** The skill's folder (holding SKILL.md). */
+  dir: string
+  file: string
+  /** Sources whose skill of the same name this one replaced. */
+  overrides?: SkillSource[]
+}
+
+export type Registry = {
+  /** Enabled skills, by name. */
+  skills: Skill[]
+  /** Skills turned off with skills.disable. */
+  disabled: Skill[]
+  /** Folders or SKILL.md files that could not be used, with why. */
+  problems: string[]
+}
+
+export const PREBUILT_DIR = path.resolve(import.meta.dir, "..", "..", "skills")
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const MAX_NAME = 64
+const MAX_DESCRIPTION = 1024
+const MAX_FILE = 100_000
+
+/** The folders each source reads, in precedence order. `repo` adds its own .forgeqe/skills (and .claude/.agents with external). */
+export function skillRoots(cfg: SkillsConfig, repo?: string): { source: SkillSource; dir: string }[] {
+  const roots: { source: SkillSource; dir: string }[] = [{ source: "prebuilt", dir: PREBUILT_DIR }]
+  if (cfg.external) {
+    const home = os.homedir()
+    for (const d of [path.join(home, ".claude", "skills"), path.join(home, ".agents", "skills")]) roots.push({ source: "external", dir: d })
+    if (repo) for (const d of [path.join(repo, ".claude", "skills"), path.join(repo, ".agents", "skills")]) roots.push({ source: "external", dir: d })
+  }
+  roots.push({ source: "user", dir: cfg.userDir })
+  roots.push({ source: "project", dir: cfg.projectDir })
+  const repoProject = repo ? path.join(projectDir(repo), "skills") : ""
+  if (repoProject && path.resolve(repoProject) !== path.resolve(cfg.projectDir)) roots.push({ source: "project", dir: repoProject })
+  for (const d of cfg.dirs) roots.push({ source: "extra", dir: d })
+  const seen = new Set<string>()
+  return roots.filter((r) => {
+    const key = path.resolve(r.dir)
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+/** Frontmatter and body of a SKILL.md, or why it cannot be read. */
+export function parseSkillFile(text: string): { meta: Record<string, unknown>; body: string } | { error: string } {
+  const src = text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n")
+  if (!src.startsWith("---\n")) return { error: "SKILL.md must start with YAML frontmatter between --- lines" }
+  const end = src.indexOf("\n---", 4)
+  if (end < 0) return { error: "the frontmatter has no closing --- line" }
+  let meta: unknown
+  try {
+    meta = YAML.parse(src.slice(4, end))
+  } catch (err) {
+    const why = (err as Error).message.split("\n")[0]
+    const hint = /mapping/i.test(why) ? '; a value containing ": " needs quotes, e.g. description: "Use when …: …"' : ""
+    return { error: `the frontmatter is not valid YAML (${why})${hint}` }
+  }
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return { error: "the frontmatter must be a YAML mapping" }
+  const rest = src.slice(end + 4)
+  return { meta: meta as Record<string, unknown>, body: rest.replace(/^[^\n]*\n/, "").trim() }
+}
+
+function readSkill(dir: string, source: SkillSource): Skill | { problem: string } {
+  const file = path.join(dir, "SKILL.md")
+  const folder = path.basename(dir)
+  const where = `${source} skill ${file}`
+  let text: string
+  try {
+    if (statSync(file).size > MAX_FILE) return { problem: `${where}: larger than ${MAX_FILE / 1000} KB` }
+    text = readFileSync(file, "utf8")
+  } catch (err) {
+    return { problem: `${where}: ${(err as Error).message}` }
+  }
+  const parsed = parseSkillFile(text)
+  if ("error" in parsed) return { problem: `${where}: ${parsed.error}` }
+  const { meta } = parsed
+  const name = typeof meta.name === "string" ? meta.name.trim() : ""
+  const description = typeof meta.description === "string" ? meta.description.replace(/\s+/g, " ").trim() : ""
+  if (!name) return { problem: `${where}: name is missing` }
+  if (!NAME.test(name) || name.length > MAX_NAME) return { problem: `${where}: name "${name}" must be lowercase words joined by hyphens, at most ${MAX_NAME} characters` }
+  if (name !== folder) return { problem: `${where}: name "${name}" must match its folder "${folder}"` }
+  if (!description) return { problem: `${where}: description is missing` }
+  if (description.length > MAX_DESCRIPTION) return { problem: `${where}: description is longer than ${MAX_DESCRIPTION} characters` }
+  let agents = DEFAULT_AGENTS
+  if (meta.agents !== undefined) {
+    // "webpilot" is ForgeQE's name from before the rename.
+    const raw = (Array.isArray(meta.agents) ? meta.agents.map((a) => String(a).trim()) : [String(meta.agents).trim()]).map((a) => (a === "webpilot" ? "forgeqe" : a))
+    const unknown = raw.filter((a) => !SKILL_AGENTS.includes(a as SkillAgent))
+    if (unknown.length || !raw.length) return { problem: `${where}: agents must list forgeqe, scribe, or browser; got ${raw.join(", ") || "nothing"}` }
+    agents = [...new Set(raw as SkillAgent[])]
+  }
+  return { name, description, agents, source, dir, file }
+}
+
+function skillDirs(root: string): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(root)
+  } catch {
+    return []
+  }
+  return entries
+    .filter((e) => !e.startsWith("."))
+    .map((e) => path.join(root, e))
+    .filter((d) => {
+      try {
+        return statSync(d).isDirectory() && existsSync(path.join(d, "SKILL.md"))
+      } catch {
+        return false
+      }
+    })
+    .sort()
+}
+
+/** Every skill from the configured sources: a later source replaces an earlier one by name, then skills.disable applies. */
+export function loadSkills(cfg: SkillsConfig | undefined, repo?: string): Registry {
+  if (!cfg?.enabled) return { skills: [], disabled: [], problems: [] }
+  const byName = new Map<string, Skill>()
+  const problems: string[] = []
+  for (const root of skillRoots(cfg, repo)) {
+    for (const dir of skillDirs(root.dir)) {
+      // A copy forgeqe init made and nobody changed is still the built-in skill: the built-in (and its updates) wins.
+      if (root.source !== "prebuilt" && copyState(root.dir, path.basename(dir)) === "unchanged" && existsSync(path.join(PREBUILT_DIR, path.basename(dir), "SKILL.md"))) continue
+      const s = readSkill(dir, root.source)
+      if ("problem" in s) {
+        problems.push(s.problem)
+        continue
+      }
+      const before = byName.get(s.name)
+      if (before) s.overrides = [...(before.overrides || []), before.source]
+      byName.set(s.name, s)
+    }
+  }
+  const off = new Set(cfg.disable)
+  const all = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))
+  for (const name of off) if (!byName.has(name)) problems.push(`skills.disable names "${name}", which no source has`)
+  return { skills: all.filter((s) => !off.has(s.name)), disabled: all.filter((s) => off.has(s.name)), problems }
+}
+
+/** The enabled skills one agent may use. */
+export function skillsFor(reg: Registry, agent: SkillAgent): Skill[] {
+  return reg.skills.filter((s) => s.agents.includes(agent))
+}
+
+export function findSkill(reg: Registry, name: string): Skill | undefined {
+  return reg.skills.find((s) => s.name === name) || reg.disabled.find((s) => s.name === name)
+}
+
+/** SKILL.md without its frontmatter. */
+export function skillBody(skill: Skill): string {
+  const parsed = parseSkillFile(readFileSync(skill.file, "utf8"))
+  return "error" in parsed ? "" : parsed.body
+}
+
+/** "name: description" lines, for prompts. */
+export function catalogLines(skills: Skill[]): string[] {
+  return skills.map((s) => `- ${s.name}: ${s.description}`)
+}
+
+/**
+ * A folder of links to the given skills, so the agent runtime sees exactly the registry's choice (one copy per name,
+ * whatever folder it came from). `remove` deletes the links, never the skills.
+ */
+export function linkSkills(skills: Skill[]): { dir: string; remove(): void } | null {
+  if (!skills.length) return null
+  const dir = mkdtempSync(path.join(os.tmpdir(), "forgeqe-skills-"))
+  for (const s of skills) {
+    try {
+      symlinkSync(s.dir, path.join(dir, s.name), process.platform === "win32" ? "junction" : "dir")
+    } catch {
+      // A skill that cannot be linked is left out rather than stopping the session.
+    }
+  }
+  return {
+    dir,
+    remove() {
+      try {
+        for (const e of readdirSync(dir)) unlinkSync(path.join(dir, e))
+        rmdirSync(dir)
+      } catch {
+        // already gone
+      }
+    },
+  }
+}
+
+/** Create the folder a new skill goes in; returns its SKILL.md path. */
+export function ensureSkillDir(root: string, name: string): string {
+  const dir = path.join(root, name)
+  mkdirSync(dir, { recursive: true })
+  return path.join(dir, "SKILL.md")
+}

package/src/skills/scaffold.ts

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import YAML from "yaml"
+
+import { ensureSkillDir, SKILL_AGENTS, type SkillAgent } from "./registry.ts"
+
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+const BODY: Record<SkillAgent, string> = {
+  browser: `Write what the browser agent should know about this site or widget, as short imperative rules. For example:
+
+- Lookup fields open a dropdown after typing; pick the row whose text matches exactly, then wait for the field to show it.
+- The form saves with the Save button in the command bar; wait until "Saving..." disappears before the next step.`,
+  scribe: `Write the conventions a test in this repository must follow, as short imperative rules. For example:
+
+- Tests live in tests/e2e and use the fixtures in tests/fixtures/auth.ts to sign in.
+- Run one test with: npx playwright test <file> --project=chromium`,
+  forgeqe: `Write the steps ForgeQE's agent should follow for this kind of request, as short imperative rules. For example:
+
+1. Run the smoke cases in checks/smoke.yaml with run_test_cases.
+2. Post the summary to the release ticket named in the request.`,
+}
+
+export type NewSkill = { name: string; description: string; agents: SkillAgent[]; body?: string }
+
+/** Write `<root>/<name>/SKILL.md`; refuses an existing skill. Returns the file. */
+export function newSkill(root: string, skill: NewSkill): string {
+  const name = skill.name.trim()
+  if (!NAME.test(name) || name.length > 64) throw new Error(`A skill name is lowercase words joined by hyphens (e.g. dynamics-date-picker); got "${name}".`)
+  const description = skill.description.replace(/\s+/g, " ").trim()
+  if (!description) throw new Error("A skill needs a description: when it applies, in one or two sentences. The model chooses skills by it.")
+  const agents = skill.agents.length ? skill.agents : (["forgeqe", "scribe"] as SkillAgent[])
+  const bad = agents.filter((a) => !SKILL_AGENTS.includes(a))
+  if (bad.length) throw new Error(`Unknown agent ${bad.join(", ")}; use forgeqe, scribe, or browser.`)
+  const file = ensureSkillDir(root, name)
+  if (existsSync(file)) throw new Error(`${file} already exists.`)
+  const front = YAML.stringify({ name, description, agents }, { lineWidth: 0 }).trim()
+  const body = skill.body?.trim() || BODY[agents.includes("browser") ? "browser" : agents.includes("scribe") ? "scribe" : "forgeqe"]
+  writeFileSync(file, `---\n${front}\n---\n\n# ${name}\n\n${body}\n`)
+  return file
+}
+
+/** A note when git would not commit `file` (e.g. the repo ignores all of .forgeqe/), or null. */
+export function ignoredNote(file: string): string | null {
+  const r = spawnSync("git", ["check-ignore", "-q", path.basename(file)], { cwd: path.dirname(file), stdio: "ignore" })
+  if (r.status !== 0) return null
+  return `git ignores ${file}, so the skill would not be shared. If .gitignore has .forgeqe/, replace it with .forgeqe/* and !.forgeqe/skills/.`
+}
+
+/** Add or remove `name` in skills.disable of forgeqe.yaml, keeping its comments. Returns whether the file changed. */
+export function setSkillDisabled(configPath: string, name: string, disabled: boolean): boolean {
+  const doc = YAML.parseDocument(existsSync(configPath) ? readFileSync(configPath, "utf8") : "")
+  const raw = doc.getIn(["skills", "disable"])
+  const current = YAML.isSeq(raw) ? raw.items.map((i) => String(YAML.isScalar(i) ? i.value : i)) : []
+  const next = disabled ? [...new Set([...current, name])] : current.filter((n) => n !== name)
+  if (next.length === current.length && next.every((n, i) => n === current[i])) return false
+  if (doc.get("skills") === false) throw new Error(`Skills are turned off in ${configPath} (skills: false).`)
+  if (!YAML.isMap(doc.get("skills"))) doc.set("skills", doc.createNode({}))
+  if (next.length) doc.setIn(["skills", "disable"], doc.createNode(next, { flow: true }))
+  else doc.deleteIn(["skills", "disable"])
+  writeFileSync(configPath, doc.toString())
+  return true
+}

package/src/skills/select.ts

@@ -0,0 +1,37 @@
+import type { SkillsConfig } from "../config.ts"
+import type { EngineRequest } from "../engine/bridge.ts"
+import { loadSkills, skillBody, skillsFor } from "./registry.ts"
+
+/** Skills the engine chose for a goal, so later runs of it (monitor rounds, a suite's retries) skip the choice. */
+const chosenByGoal = new Map<string, string[]>()
+
+export type BrowserSkills = Pick<EngineRequest, "skills" | "skillsPick" | "skillsMaxChars"> & { unknown: string[] }
+
+/**
+ * What the engine gets for a run's browser skills. `names` are the skills the caller picked (ForgeQE's agent or
+ * --skill; empty means none); without them the engine chooses from every browser skill, once per goal.
+ */
+export function browserSkills(cfg: SkillsConfig | undefined, goal: string, names?: string[], repo?: string): BrowserSkills {
+  const none: BrowserSkills = { unknown: [] }
+  const catalog = skillsFor(loadSkills(cfg, repo), "browser")
+  if (!cfg || !catalog.length) return { unknown: names || [] }
+  const remembered = names ? undefined : chosenByGoal.get(goal)
+  const given = names || remembered
+  const entry = (s: (typeof catalog)[number]) => ({ name: s.name, description: s.description, body: skillBody(s) })
+  if (given) {
+    const picked = given.flatMap((n) => catalog.filter((s) => s.name === n))
+    const unknown = given.filter((n) => !catalog.some((s) => s.name === n))
+    if (!picked.length) return { ...none, unknown }
+    return { skills: picked.map(entry), skillsPick: "given", skillsMaxChars: cfg.browserMaxChars, unknown }
+  }
+  return { skills: catalog.map(entry), skillsPick: "choose", skillsMaxChars: cfg.browserMaxChars, unknown: [] }
+}
+
+/** After a run where the engine chose (`used` is set, empty when nothing fit): remember the choice for the goal. */
+export function rememberChoice(goal: string, pick: BrowserSkills["skillsPick"], used: string[] | undefined): void {
+  if (pick === "choose" && used) chosenByGoal.set(goal, used)
+}
+
+export function forgetChoices(): void {
+  chosenByGoal.clear()
+}

package/src/skills/view.ts

@@ -0,0 +1,44 @@
+import path from "node:path"
+
+import type { SkillsConfig } from "../config.ts"
+import { skillBody, skillRoots, skillsFor, type Registry, type Skill, type SkillAgent } from "./registry.ts"
+
+const AGENT_LABEL: Record<SkillAgent, string> = { forgeqe: "ForgeQE's agent", scribe: "Scribe (tests)", browser: "Browser agent" }
+
+const short = (text: string, max: number) => (text.length > max ? `${text.slice(0, max - 1)}…` : text)
+
+function origin(s: Skill): string {
+  return s.overrides?.length ? `${s.source}, replaces ${s.overrides.join(", ")}` : s.source
+}
+
+/** The skills each agent can use, the disabled ones, problems, and the folders read. */
+export function skillsOverview(reg: Registry, cfg: SkillsConfig | undefined, repo?: string): string {
+  if (!cfg?.enabled) return "Skills are turned off (skills: false or skills.enabled: false in forgeqe.yaml)."
+  const width = Math.max(12, ...[...reg.skills, ...reg.disabled].map((s) => s.name.length)) + 2
+  const row = (s: Skill) => `  ${s.name.padEnd(width)}${`[${origin(s)}]`.padEnd(30)} ${short(s.description, 90)}`
+  const out: string[] = []
+  for (const agent of ["forgeqe", "scribe", "browser"] as SkillAgent[]) {
+    const list = skillsFor(reg, agent)
+    out.push(`${AGENT_LABEL[agent]} (${list.length})`)
+    out.push(...(list.length ? list.map(row) : ["  none"]))
+  }
+  if (reg.disabled.length) out.push("", "Disabled (skills.disable)", ...reg.disabled.map(row))
+  if (reg.problems.length) out.push("", "Problems", ...reg.problems.map((p) => `  ✗ ${p}`))
+  const home = process.env.HOME || ""
+  const tidy = (d: string) => (home && d.startsWith(home) ? `~${d.slice(home.length)}` : path.relative(process.cwd(), d) || ".")
+  out.push("", "Folders read (later ones replace a skill of the same name)")
+  for (const r of skillRoots(cfg, repo)) out.push(`  ${r.source.padEnd(9)}${tidy(r.dir)}`)
+  return out.join("\n")
+}
+
+/** One skill: where it comes from, who uses it, and its instructions. */
+export function skillDetail(s: Skill, disabled = false): string {
+  return [
+    `${s.name}${disabled ? " (disabled)" : ""}`,
+    `  ${s.description}`,
+    `  used by: ${s.agents.map((a) => AGENT_LABEL[a]).join(", ")}`,
+    `  from:    ${origin(s)} · ${s.file}`,
+    "",
+    skillBody(s),
+  ].join("\n")
+}

package/src/suite/report.ts

@@ -0,0 +1,135 @@
+import { writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { stepVerdictLines, type CaseResult } from "../cases/types.ts"
+import { renderReport } from "../report/html.ts"
+import type { Usage } from "../types.ts"
+import { addCost, addUsage, usageLine, type Cost } from "../usage.ts"
+import type { SuiteResult } from "./run.ts"
+
+const xmlEsc = (s: string) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "")
+
+export function counts(results: CaseResult[]) {
+  return {
+    total: results.length,
+    passed: results.filter((r) => r.status === "passed").length,
+    failed: results.filter((r) => r.status === "failed").length,
+    errors: results.filter((r) => r.status === "error").length,
+    stopped: results.filter((r) => r.status === "stopped").length,
+    coded: results.filter((r) => r.code).length,
+    codePassed: results.filter((r) => r.code?.status === "passed").length,
+  }
+}
+
+export function writeReports(s: Omit<SuiteResult, "files">): SuiteResult["files"] {
+  const files = { junit: path.join(s.dir, "junit.xml"), html: path.join(s.dir, "report.html"), json: path.join(s.dir, "suite.json") }
+  writeFileSync(files.junit, junit(s))
+  writeFileSync(files.html, renderReport({ title: s.name, startedAt: s.startedAt, ms: s.ms, stopped: s.stopped, dir: s.dir, results: s.results, posted: s.writeBack, env: s.env }))
+  writeFileSync(files.json, `${JSON.stringify({ ...s, files }, null, 2)}\n`)
+  return files
+}
+
+function junit(s: Omit<SuiteResult, "files">): string {
+  const c = counts(s.results)
+  const secs = (ms: number) => (ms / 1000).toFixed(3)
+  const cases = s.results.map((r) => {
+    const out = [r.summary, ...stepVerdictLines(r), r.runDir ? `Run: ${r.runDir}` : "", r.case.url ? `Case: ${r.case.url}` : ""]
+    for (const w of s.writeBack.filter((w) => w.caseId === r.case.id && w.url)) out.push(`${w.text}: ${w.url}`)
+    if (r.code) out.push(`Test ${r.code.status}: ${r.code.testFile || "(none)"}${r.code.command ? ` (${r.code.command})` : ""}`)
+    else if (r.codeSkipped) out.push(`No test: ${r.codeSkipped}`)
+    const body =
+      r.status === "failed"
+        ? `<failure message="${xmlEsc(firstLine(r.summary) || "failed")}">${xmlEsc(r.summary)}</failure>`
+        : r.status === "error"
+          ? `<error message="${xmlEsc(firstLine(r.summary) || "error")}">${xmlEsc(r.summary)}</error>`
+          : r.status === "stopped"
+            ? `<skipped message="stopped"/>`
+            : ""
+    return `    <testcase classname="forgeqe.${r.case.source}" name="${xmlEsc(`${r.case.id} ${r.case.title}`)}" time="${secs(r.ms)}">${body}<system-out>${xmlEsc(out.filter(Boolean).join("\n"))}</system-out></testcase>`
+  })
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<testsuites name="${xmlEsc(s.name)}" tests="${c.total}" failures="${c.failed}" errors="${c.errors}" skipped="${c.stopped}" time="${secs(s.ms)}">`,
+    `  <testsuite name="ForgeQE" tests="${c.total}" failures="${c.failed}" errors="${c.errors}" skipped="${c.stopped}" time="${secs(s.ms)}" timestamp="${s.startedAt}">`,
+    ...cases,
+    `  </testsuite>`,
+    `</testsuites>`,
+    "",
+  ].join("\n")
+}
+
+/** Every case's browser and Scribe tokens together, and their cost (unset when any part has no price). */
+export function suiteUsage(results: CaseResult[]): { usage: Usage; cost?: Cost } {
+  let usage: Usage = { input: 0, output: 0 }
+  let cost: Cost | undefined
+  let priced = true
+  for (const r of results) {
+    for (const [u, c] of [[r.usage, r.cost], [r.codeUsage, r.codeCost]] as const) {
+      if (!u || (!u.input && !u.output)) continue
+      usage = addUsage(usage, u)
+      if (c) cost = addCost(cost, c)
+      else priced = false
+    }
+  }
+  return { usage, cost: priced ? cost : undefined }
+}
+
+/** The end-of-suite summary for the terminal. */
+export function formatSuite(s: SuiteResult, cwd = process.cwd()): string {
+  const c = counts(s.results)
+  const tokens = s.results.reduce((n, r) => n + r.tokens, 0)
+  const head = `${s.stopped ? "■ Suite stopped" : c.passed === c.total ? "✓ Suite passed" : "✗ Suite failed"} · ${c.passed}/${c.total} passed · ${duration(s.ms)} · ${(tokens / 1000).toFixed(1)}K tokens`
+  const total = suiteUsage(s.results)
+  const lines = [head, ""]
+  if (total.usage.input || total.usage.output) lines.push(`Usage     ${usageLine(total.usage, total.cost)}`, "")
+  for (const r of s.results) {
+    const code = r.code ? `  test ${r.code.status}${r.code.testFile ? `: ${r.code.testFile}` : ""}` : ""
+    lines.push(`${MARK[r.status]} ${r.case.id}  ${r.case.title}  (${duration(r.ms)})${code}`)
+    if (r.status !== "passed" && r.summary) lines.push(`    ${firstLine(r.summary)}`)
+    const failedStep = r.stepResults?.find((v) => v.status === "failed")
+    if (r.status !== "passed" && failedStep) lines.push(`    step ${failedStep.step} failed${failedStep.actual ? `: ${firstLine(failedStep.actual)}` : ""}`)
+  }
+  if (s.writeBack.length) {
+    lines.push("")
+    for (const w of s.writeBack) lines.push(`${w.error ? "✗" : "↑"} ${w.text}${w.url ? `  ${w.url}` : ""}${w.error ? `: ${w.error}` : ""}`)
+  }
+  const show = (f: string) => path.relative(cwd, f) || f
+  lines.push("", `Report    ${show(s.files.html)}`, `JUnit     ${show(s.files.junit)}`)
+  return lines.join("\n")
+}
+
+/** GitHub Actions job summary (GITHUB_STEP_SUMMARY): the result line and one table row per case. */
+export function markdownSummary(s: SuiteResult): string {
+  const c = counts(s.results)
+  const cell = (t: string) => t.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim()
+  const head = s.stopped ? "■ Suite stopped" : c.passed === c.total ? "✓ Suite passed" : "✗ Suite failed"
+  const rows = s.results.map((r) => {
+    const test = r.code ? `${r.code.status}${r.code.testFile ? ` \`${cell(r.code.testFile)}\`` : ""}` : ""
+    const steps = r.stepResults?.length && r.case.steps.length ? `${r.stepResults.filter((v) => v.status === "passed").length}/${r.case.steps.length}` : ""
+    const bug = s.writeBack.find((w) => w.caseId === r.case.id && w.source === "bugs" && w.url)
+    const result = cell(r.status === "passed" ? "" : firstLine(r.summary)) + (bug ? ` [${cell(bug.text.split(":")[0])}](${bug.url})` : "")
+    return `| ${MARK[r.status]} | ${cell(r.case.id)} | ${cell(r.case.title)} | ${steps} | ${duration(r.ms)} | ${result} | ${test} |`
+  })
+  const posted = s.writeBack.filter((w) => !w.caseId || w.error).map((w) => `- ${w.error ? "✗" : "↑"} ${w.text}${w.url ? ` ${w.url}` : ""}${w.error ? `: ${w.error}` : ""}`)
+  return [
+    `### ${head} · ${c.passed}/${c.total} passed · ${duration(s.ms)}`,
+    "",
+    "| | Case | Title | Steps | Time | Result | Test |",
+    "|---|---|---|---|---|---|---|",
+    ...rows,
+    ...(posted.length ? ["", ...posted] : []),
+    "",
+  ].join("\n")
+}
+
+function firstLine(s: string): string {
+  return s.split("\n")[0].slice(0, 200)
+}
+
+const MARK = { passed: "✓", failed: "✗", error: "!", stopped: "■" } as const
+
+function duration(ms: number): string {
+  const s = Math.round(ms / 1000)
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`
+}