jackherd 0.0.1 → 1.0.1

package/src/plans/sprint-html.ts

@@ -0,0 +1,301 @@
+import { contextLabel } from '../context'
+import { CLI_NAME } from '../version/release'
+import type { LinkChip } from './link-chips'
+import { renderPlanMarkdown, scrollable } from './markdown-html'
+import { phaseList, plannedPhaseCount } from './planned'
+import type {
+  PageLane,
+  PagePhase,
+  PagePlanDocument,
+  PagePlanned,
+  PagePlanRow,
+  PagePlanTable,
+  PageStep,
+  PlanRef,
+  SprintPage,
+} from './sprint-page'
+import { phaseCountOf, phaseStateOf, statusSymbol, statusWord } from './symbols'
+import { laneMarkText, TEXTS } from './texts'
+
+const BAR_PERCENT = 100
+
+const STYLE = `
+:root { color-scheme: light dark; --bg: #fafaf9; --panel: #ffffff; --fg: #1c1917; --muted: #78716c; --line: #e7e5e4;
+  --accent: #2563eb; --ok: #15803d; --warn: #b45309; --bad: #b91c1c; --bar: #e7e5e4; }
+@media (prefers-color-scheme: dark) { :root { --bg: #131315; --panel: #1c1c1f; --fg: #e7e5e4; --muted: #a8a29e;
+  --line: #2e2e33; --accent: #60a5fa; --ok: #4ade80; --warn: #fbbf24; --bad: #f87171; --bar: #2e2e33; } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, sans-serif; }
+main { max-width: 1040px; margin: 0 auto; padding: 24px 16px 64px; }
+a { color: var(--accent); }
+code { font: 0.9em ui-monospace, monospace; background: var(--line); padding: 1px 4px; border-radius: 4px; }
+h1 { margin: 0 0 4px; font-size: 1.6rem; }
+h2 { margin: 32px 0 12px; font-size: 1.15rem; }
+h3 { margin: 16px 0 4px; font-size: 1rem; }
+.meta, .muted { color: var(--muted); font-size: 0.9rem; }
+.goal p { margin: 8px 0; white-space: pre-line; }
+.lane { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; margin: 12px 0; }
+.lane > summary { display: flex; flex-wrap: wrap; gap: 4px 12px; align-items: center; padding: 10px 14px; cursor: pointer; }
+.lane.closed { opacity: 0.6; }
+.name { font-size: 1.02rem; }
+.word { color: var(--muted); }
+.context { color: var(--muted); font-size: 0.9rem; font-variant-numeric: tabular-nums; }
+.context.warn { color: var(--warn); } .context.alert { color: var(--bad); }
+.bar { display: inline-block; width: 120px; height: 8px; background: var(--bar); border-radius: 4px; overflow: hidden; }
+.bar i { display: block; height: 100%; background: var(--ok); }
+.count { font-variant-numeric: tabular-nums; }
+.grow { flex: 1; }
+.lane-body { padding: 0 14px 14px; border-top: 1px solid var(--line); }
+.step { margin-top: 12px; }
+.step-meta { margin: 0; color: var(--muted); font-size: 0.88rem; }
+.note { margin: 4px 0 0; }
+ul.phases { list-style: none; margin: 6px 0 0; padding: 0; }
+.phase { padding: 4px 0; border-top: 1px dashed var(--line); }
+.phase:first-child { border-top: 0; }
+.phase .count { display: inline-block; min-width: 4.5em; margin-right: .4em; font-variant-numeric: tabular-nums; }
+.state-all .count { color: var(--ok); }
+.state-missing, .state-empty { color: var(--muted); }
+.deps { color: var(--muted); font-size: 0.85rem; margin-left: 1.4em; }
+details.items { margin-left: 1.4em; }
+details.items summary { cursor: pointer; color: var(--muted); font-size: 0.88rem; }
+ul.items { margin: 4px 0 0; padding-left: 1.2em; }
+.pr { margin: 2px 0; }
+.checks-passed { color: var(--ok); } .checks-failed { color: var(--bad); } .checks-pending { color: var(--warn); }
+/* tables sit in .table-scroll so a wide one scrolls sideways */
+.planned { opacity: 0.7; margin: 10px 0; }
+.planned > summary { cursor: pointer; }
+.table-scroll { overflow-x: auto; margin: 8px 0; }
+.chips { flex-basis: 100%; display: flex; flex-wrap: wrap; gap: 6px; }
+.chip { display: inline-flex; gap: 4px; align-items: baseline; border: 1px solid var(--line); border-radius: 999px; padding: 1px 10px; font-size: 0.85rem; }
+.chip .icon { margin-right: 4px; }
+table { border-collapse: collapse; width: 100%; background: var(--panel); }
+table.plans { table-layout: fixed; }
+table.plans .bar { display: block; width: 100%; margin-bottom: 2px; }
+.table-caption { margin: 16px 0 4px; }
+.gh { font-size: 0.8rem; color: var(--muted); }
+.plan { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; margin: 10px 0; }
+.plan > summary { display: flex; flex-wrap: wrap; gap: 4px 12px; align-items: center; padding: 10px 14px; cursor: pointer; }
+.plan-body { padding: 0 14px 14px; border-top: 1px solid var(--line); overflow-x: auto; }
+.plan-body h3, .plan-body h4, .plan-body h5 { margin: 18px 0 6px; }
+th, td { border: 1px solid var(--line); padding: 6px 10px; text-align: left; vertical-align: top; }
+th { color: var(--muted); font-weight: 600; font-size: 0.85rem; }
+footer { margin-top: 40px; color: var(--muted); font-size: 0.85rem; }
+`
+
+export const escapeHtml = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+/** A private-use character that cannot occur in escaped text; it keeps a finished link out of the bold and code passes. */
+const PLACEHOLDER = '\uE000'
+const SAFE_LINK = /^https?:\/\//
+const SAFE_TARGET = /^(?:https?|file):\/\/|^#/
+
+/** A link target the page may use: http(s) for the web, `file:` for the local checkout, `#` for a place on the page; never a script. */
+export const isSafeTarget = (target: string): boolean => SAFE_TARGET.test(target)
+
+const linked = (target: string | null, label: string): string =>
+  target !== null && isSafeTarget(target) ? `<a href="${escapeHtml(target)}">${label}</a>` : label
+
+/** A plan's title linked to its section on the page, with a small link to its file beside it. */
+const planLink = (plan: PlanRef | null, label: string): string => {
+  if (plan === null) return label
+  const file = linked(plan.file, 'on GitHub')
+  return plan.anchor === null
+    ? linked(plan.file, label)
+    : `${linked(`#${plan.anchor}`, label)} <span class="gh">(${file})</span>`
+}
+
+/**
+ * Escaped text with the markdown a sprint document uses inline: `**bold**`, `` `code` `` and
+ * `[text](https://…)`; a link that is not http(s) is shown as its text, never as a link.
+ */
+export const inlineMarkdown = (text: string): string => {
+  const anchors: string[] = []
+  const withoutLinks = escapeHtml(text).replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label: string, href: string) => {
+    anchors.push(SAFE_LINK.test(href) ? `<a href="${href}">${label}</a>` : label)
+    return `${PLACEHOLDER}${anchors.length - 1}${PLACEHOLDER}`
+  })
+  return withoutLinks
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/`([^`]+)`/g, '<code>$1</code>')
+    .replace(new RegExp(`${PLACEHOLDER}(\\d+)${PLACEHOLDER}`, 'g'), (_, index: string) => anchors[Number(index)])
+}
+
+const plainMarkdown = (text: string): string => text.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/\*\*|`/g, '')
+
+const timestamp = (date: Date): string => `${date.toISOString().slice(0, 16).replace('T', ' ')} UTC`
+
+const baseRefLine = ({ baseRef }: SprintPage): string => {
+  const commit = baseRef.commit ? ` @ <code>${escapeHtml(baseRef.commit)}</code>` : ' (not found)'
+  const committed = baseRef.committedAt ? `, committed ${escapeHtml(baseRef.committedAt)}` : ''
+  const fetched = baseRef.fetchedAt ? `last fetch ${timestamp(baseRef.fetchedAt)}` : 'last fetch unknown'
+  return `${escapeHtml(baseRef.name)}${commit}${committed} · ${fetched}`
+}
+
+const percent = (done: number, total: number): number => (total === 0 ? 0 : Math.floor((done / total) * BAR_PERCENT))
+
+const bar = (done: number, total: number): string =>
+  total === 0
+    ? ''
+    : `<span class="bar" role="img" aria-label="${done} of ${total}"><i style="width:${percent(done, total)}%"></i></span> <span class="count">${done}/${total}</span>`
+
+const branchLine = ({ branch, ahead, dirty }: PageLane): string => {
+  if (!branch) return `<span class="muted">${escapeHtml(TEXTS.noWorktree)}</span>`
+  const marks = [ahead ? `↑${ahead}` : '', dirty ? `±${dirty}` : ''].filter(Boolean).join(' ')
+  return `⎇ <code>${escapeHtml(branch)}</code>${marks ? ` ${marks}` : ''}`
+}
+
+const pullRequestLine = (lane: PageLane): string =>
+  lane.pullRequests
+    .map(
+      (pull) =>
+        `<div class="pr">↗ ${linked(pull.url, `#${pull.number}`)} <span class="checks-${pull.checks}">${escapeHtml(TEXTS.checks[pull.checks])}</span> ${escapeHtml(pull.draft ? TEXTS.draft : '')}${escapeHtml(pull.title)}</div>`,
+    )
+    .join('')
+
+const phaseTitle = (phase: PagePhase): string =>
+  phase.title === null ? `<span class="muted">${escapeHtml(TEXTS.notInPlan)}</span>` : inlineMarkdown(phase.title)
+
+const openItems = (phase: PagePhase): string => {
+  const open = phase.items.filter((item) => !item.done)
+  if (open.length === 0) return ''
+  const rows = open.map((item) => `<li>${inlineMarkdown(item.text)}</li>`).join('')
+  return `<details class="items"><summary>${open.length} open</summary><ul class="items">${rows}</ul></details>`
+}
+
+const phaseRow = (phase: PagePhase): string => {
+  const state = phaseStateOf(phase)
+  const deps = phase.dependsOn
+    ? `<div class="deps">depends on ${inlineMarkdown(plainMarkdown(phase.dependsOn))}</div>`
+    : ''
+  return `<li class="phase state-${state}"><span class="count">${phaseCountOf(phase)}</span><strong>P${escapeHtml(phase.id)}</strong> ${phaseTitle(phase)}${deps}${openItems(phase)}</li>`
+}
+
+const stepBlock = (step: PageStep): string => {
+  const title = planLink(step.plan, escapeHtml(step.planTitle))
+  const facts = [
+    step.model ? `Model: ${escapeHtml(step.model)}` : '',
+    step.startsAfter ? `Starts after: ${inlineMarkdown(plainMarkdown(step.startsAfter))}` : '',
+  ]
+    .filter(Boolean)
+    .join(' · ')
+  const phases = step.phases.length > 0 ? `<ul class="phases">${step.phases.map(phaseRow).join('')}</ul>` : ''
+  const note = step.note ? `<p class="note">${inlineMarkdown(step.note)}</p>` : ''
+  return `<section class="step"><h3>${title}</h3>${facts ? `<p class="step-meta">${facts}</p>` : ''}${note}${phases}</section>`
+}
+
+const laneBlock = (lane: PageLane): string => {
+  const port = lane.port === null ? '' : `<span class="meta">port ${lane.port}</span>`
+  const closed = lane.closed ? '<span class="meta">closed</span>' : ''
+  const markText = laneMarkText(lane)
+  const mark = markText ? `<span class="meta">${escapeHtml(markText)}</span> ` : ''
+  const context = lane.context
+    ? `<span class="context ${lane.context.level}" title="context window">${contextLabel(lane.context.share)}</span> `
+    : ''
+  const summary = `<summary><span title="${escapeHtml(statusWord(lane.agent))}">${statusSymbol(lane.agent)}</span> <strong class="name">${escapeHtml(lane.name)}</strong> <span class="word">${escapeHtml(statusWord(lane.agent))}</span> ${port} ${closed}${mark}<span class="grow"></span>${context}${bar(lane.done, lane.total)}</summary>`
+  const facts = `<p class="meta">${branchLine(lane)}</p>${pullRequestLine(lane)}`
+  return `<details class="lane${lane.closed ? ' closed' : ''}"${lane.closed ? '' : ' open'}>${summary}<div class="lane-body">${facts}${lane.steps.map(stepBlock).join('')}</div></details>`
+}
+
+const PLAN_LINK_IN_CELL = /\[[^\]]+\]\([^)\s]+\)/
+
+const planCell = (cell: string, row: PagePlanRow): string =>
+  row.title !== null && PLAN_LINK_IN_CELL.test(cell)
+    ? cell.replace(PLAN_LINK_IN_CELL, () => planLink(row.plan, escapeHtml(row.title ?? '')))
+    : inlineMarkdown(cell)
+
+const planProgress = ({ progress }: PagePlanRow): string =>
+  progress === null || progress.total === 0
+    ? '<td class="muted">–</td>'
+    : `<td>${bar(progress.done, progress.total)}</td>`
+
+/** Column widths shared by every plans table, so tables that belong together line up. */
+const PLAN_COLUMNS = ['4%', '24%', '34%', '30%', '8%']
+
+const planColumns = (count: number): string =>
+  `<colgroup>${PLAN_COLUMNS.slice(0, count)
+    .map((width) => `<col style="width:${width}">`)
+    .join('')}</colgroup>`
+
+const planTable = ({ caption, header, rows }: PagePlanTable): string => {
+  const head = `${header.map((cell) => `<th>${escapeHtml(cell)}</th>`).join('')}<th>Checkboxes</th>`
+  const body = rows
+    .map((row) => `<tr>${row.cells.map((cell) => `<td>${planCell(cell, row)}</td>`).join('')}${planProgress(row)}</tr>`)
+    .join('')
+  const title = caption ? `<p class="table-caption">${inlineMarkdown(caption)}</p>` : ''
+  return `${title}${scrollable(`<table class="plans">${planColumns(header.length + 1)}<thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`)}`
+}
+
+const plansSection = ({ plans }: SprintPage): string =>
+  plans.length === 0 ? '' : `<h2>Plans</h2>${plans.map(planTable).join('')}`
+
+const plannedRow = ({ title, plan, phaseIds, done, total }: PagePlanned): string =>
+  `<li>${planLink(plan, escapeHtml(title))} <span class="muted">${escapeHtml(phaseList({ phaseIds }))}</span> ${bar(done, total)}</li>`
+
+/** The open phases no lane works on, dimmed and closed, so the page keeps its focus on the active lanes. */
+const plannedSection = ({ planned }: SprintPage): string => {
+  if (planned.length === 0) return ''
+  const phases = plannedPhaseCount(planned)
+  const summary = `<summary>○ ${escapeHtml(TEXTS.planned(phases, planned.length))}</summary>`
+  return `<details class="planned">${summary}<ul class="phases">${planned.map(plannedRow).join('')}</ul></details>`
+}
+
+const chip = (link: LinkChip): string => {
+  const hint = link.private ? ' <span class="muted">privat</span>' : ''
+  return `<span class="chip">${linked(link.url, `<span class="icon">${escapeHtml(link.icon)}</span>${escapeHtml(link.label)}`)}${hint}</span>`
+}
+
+/** The markdown of one plan section as HTML, kept by `renderPlanMarkdown`; calling it ahead of `renderSprintHtml` moves the work out of the render. */
+export const renderPlanBody = (doc: PagePlanDocument, page: SprintPage): string =>
+  renderPlanMarkdown(doc.markdown, { fromPath: doc.repoPath, ...page.links }, doc.anchor, doc.title)
+
+const planDocument = (doc: PagePlanDocument, page: SprintPage): string => {
+  const status = doc.status ? `<span class="muted">${inlineMarkdown(doc.status)}</span>` : ''
+  const progress = doc.progress.total > 0 ? bar(doc.progress.done, doc.progress.total) : ''
+  const chips = doc.chips.length > 0 ? `<span class="chips">${doc.chips.map(chip).join('')}</span>` : ''
+  const summary = `<summary><strong>${escapeHtml(doc.title)}</strong> ${status}<span class="grow"></span>${progress}${chips}</summary>`
+  const body = renderPlanBody(doc, page)
+  return `<details class="plan">${summary}<div class="plan-body"><a id="${escapeHtml(doc.anchor)}"></a><p class="meta">${linked(doc.file, 'on GitHub')}</p>${body}</div></details>`
+}
+
+const planDocuments = (page: SprintPage): string =>
+  page.planDocuments.length === 0
+    ? ''
+    : `<h2>Plan documents</h2>${page.planDocuments.map((doc) => planDocument(doc, page)).join('\n')}`
+
+const historyTable = ({ document }: SprintPage): string => {
+  const { header, rows } = document.history
+  if (rows.length === 0) return ''
+  const head = header.map((cell) => `<th>${escapeHtml(cell)}</th>`).join('')
+  const body = rows.map((row) => `<tr>${row.map((cell) => `<td>${inlineMarkdown(cell)}</td>`).join('')}</tr>`).join('')
+  return `<h2>History</h2>${scrollable(`<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`)}`
+}
+
+/** One page for the whole board: one file, inline CSS, light and dark by the reader's setting, no script. */
+export const renderSprintHtml = (page: SprintPage): string => {
+  const goal = page.document.goal.map((paragraph) => `<p>${inlineMarkdown(paragraph)}</p>`).join('')
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(page.title)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+<h1>${escapeHtml(page.title)}</h1>
+<p class="meta">Snapshot of ${timestamp(page.generatedAt)} · ${baseRefLine(page)}</p>
+${goal ? `<section class="goal">${goal}</section>` : ''}
+${plansSection(page)}
+<h2>Lanes</h2>
+${page.lanes.map(laneBlock).join('\n')}
+${plannedSection(page)}
+${historyTable(page)}
+${planDocuments(page)}
+<footer>Generated by <code>${CLI_NAME} plans</code>. A snapshot, not a source: the markdown files stay the truth.</footer>
+</main>
+</body>
+</html>
+`
+}

package/src/plans/sprint-page.ts

@@ -0,0 +1,287 @@
+import { join, posix } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { LinkKind } from '../config/link-kinds'
+import type { ContextReading } from '../context'
+import {
+  type ChecklistItem,
+  type PhaseProgress,
+  parsePlanPhases,
+  readPhaseDependencies,
+  readPlanHeader,
+  readSprintDocument,
+  resolvePlanPath,
+  type SprintDocument,
+} from '../plan-format'
+import type { PlanLanguage } from '../vocabulary'
+import type { LaneView } from './layout'
+import { extractLinkChips, type LinkChip } from './link-chips'
+import { planAnchorOf } from './markdown-html'
+import type { PullRequest } from './pull-requests'
+import type { Snapshot } from './snapshot'
+
+/** The base ref the page was read from: its name, its commit and when this clone last fetched it. */
+export type BaseRefInfo = { name: string; commit: string | null; committedAt: string | null; fetchedAt: Date | null }
+
+/** What the page needs besides the snapshot; read by the caller, so the page itself is a pure function. */
+export type PageContext = {
+  /** The main checkout, so a plan link can be a `file:` URL when the remote is unknown. */
+  root: string
+  generatedAt: Date
+  baseRef: BaseRefInfo
+  /** `https://github.com/<owner>/<repo>/blob/<branch>/`, null when the remote is unknown. */
+  repoBlobBase: string | null
+  /** The directory of the sprint document, relative to the repository. */
+  sprintDirectory: string
+  language: PlanLanguage
+  /** The kinds of link a plan's text is searched for, shown as chips on the plan's section. */
+  linkKinds: readonly LinkKind[]
+}
+
+export type PagePhase = {
+  id: string
+  /** Null when the plan does not have the phase. */
+  title: string | null
+  done: number
+  total: number
+  items: ChecklistItem[]
+  dependsOn: string | null
+}
+
+/**
+ * How a plan is reached from the page: the id of its section when the page carries the plan, and its file on
+ * GitHub (a `file:` URL of the checkout when the remote is unknown).
+ */
+export type PlanRef = { anchor: string | null; file: string }
+
+export type PageStep = {
+  planTitle: string
+  plan: PlanRef | null
+  model: string
+  startsAfter: string
+  note: string
+  phases: PagePhase[]
+}
+
+export type PageLane = {
+  name: string
+  port: number | null
+  closed: boolean
+  agent: string | null
+  /** How full the agent's context is; absent when the lane has no reading. */
+  context?: ContextReading | null
+  branch: string | null
+  ahead: number | null
+  dirty: number
+  pullRequests: PullRequest[]
+  steps: PageStep[]
+  done: number
+  total: number
+  /** A running lane the sprint table has no row for; absent for a lane the table lists. */
+  unlisted?: boolean
+}
+
+export type PagePlanRow = {
+  cells: string[]
+  title: string | null
+  plan: PlanRef | null
+  /** Ticked and all checkboxes over the plan's phases; null when the plan could not be read. */
+  progress: { done: number; total: number } | null
+}
+
+export type PagePlanTable = { caption: string | null; header: string[]; rows: PagePlanRow[] }
+
+/** A plan the page carries in full: its section, what its header says, and the markdown to render. */
+export type PagePlanDocument = {
+  anchor: string
+  /** Repository path of the plan file. */
+  repoPath: string
+  title: string
+  status: string
+  progress: { done: number; total: number }
+  file: string
+  markdown: string
+  chips: LinkChip[]
+}
+
+/** A plan with open phases no lane with an agent leads, as the page lists it; `plan` links its section or its file. */
+export type PagePlanned = {
+  title: string
+  plan: PlanRef
+  phaseIds: string[]
+  done: number
+  total: number
+}
+
+export type SprintPage = {
+  title: string
+  generatedAt: Date
+  baseRef: BaseRefInfo
+  document: SprintDocument
+  plans: PagePlanTable[]
+  lanes: PageLane[]
+  planDocuments: PagePlanDocument[]
+  planned: PagePlanned[]
+  /** What the renderer needs to point a link of a plan at the right place. */
+  links: { anchors: ReadonlyMap<string, string>; blobBase: string | null; root: string }
+}
+
+const fileLink = (path: string, context: PageContext): string =>
+  context.repoBlobBase ? `${context.repoBlobBase}${path}` : pathToFileURL(join(context.root, path)).href
+
+/** The plans of the page by link as the sprint writes it: those whose text was read have a section. */
+const planRefs = (snapshot: Snapshot, hrefs: readonly string[], context: PageContext): Map<string, PlanRef> => {
+  const taken = new Set<string>()
+  const refs = new Map<string, PlanRef>()
+  for (const href of hrefs) {
+    if (refs.has(href)) continue
+    const path = resolvePlanPath(context.sprintDirectory, href)
+    const base = planAnchorOf(path)
+    const anchor = href in snapshot.documents.plans ? uniqueId(base, taken) : null
+    refs.set(href, { anchor, file: fileLink(path, context) })
+  }
+  return refs
+}
+
+const uniqueId = (base: string, taken: Set<string>): string => {
+  let id = base
+  for (let count = 2; taken.has(id); count += 1) id = `${base}-${count}`
+  taken.add(id)
+  return id
+}
+
+const phaseOf = (phase: PhaseProgress, dependencies: Record<string, string>): PagePhase => {
+  const numbered = phase.id.replace(/[a-z]$/, '')
+  return {
+    id: phase.id,
+    title: phase.title,
+    done: phase.done,
+    total: phase.total,
+    items: phase.items,
+    dependsOn: dependencies[phase.id] ?? dependencies[numbered] ?? null,
+  }
+}
+
+type DependenciesByPlan = ReadonlyMap<string, Record<string, string>>
+
+const laneOf = (view: LaneView, dependencies: DependenciesByPlan, refs: ReadonlyMap<string, PlanRef>): PageLane => {
+  const { progress, status, pullRequests } = view
+  return {
+    name: progress.lane.name,
+    port: progress.lane.port,
+    closed: progress.lane.closed,
+    agent: status.agent,
+    context: view.context ?? null,
+    branch: status.branch,
+    ahead: status.ahead,
+    dirty: status.dirty,
+    pullRequests,
+    done: progress.done,
+    total: progress.total,
+    ...(view.unlisted ? { unlisted: true } : {}),
+    steps: progress.steps.map(({ step, phases }) => ({
+      planTitle: step.planTitle,
+      plan: step.planHref ? (refs.get(step.planHref) ?? null) : null,
+      model: step.model,
+      startsAfter: step.startsAfter,
+      note: step.label,
+      phases: phases.map((phase) => phaseOf(phase, (step.planHref && dependencies.get(step.planHref)) || {})),
+    })),
+  }
+}
+
+const progressOf = (text: string | undefined, language: PlanLanguage): PagePlanRow['progress'] => {
+  if (text === undefined) return null
+  const items = parsePlanPhases(text, language).flatMap((phase) => phase.items)
+  return { done: items.filter((item) => item.done).length, total: items.length }
+}
+
+/** The plans the sprint lists, as the sprint lists them, with how far each plan's checkboxes are ticked. */
+const planTablesOf = (
+  snapshot: Snapshot,
+  document: SprintDocument,
+  refs: ReadonlyMap<string, PlanRef>,
+  context: PageContext,
+): PagePlanTable[] =>
+  document.planTables.map(({ caption, header, rows }) => ({
+    caption,
+    header,
+    rows: rows.map((row) => ({
+      cells: row.cells,
+      title: row.title,
+      plan: row.href ? (refs.get(row.href) ?? null) : null,
+      progress: progressOf(row.href ? snapshot.documents.plans[row.href] : undefined, context.language),
+    })),
+  }))
+
+const documentsOf = (
+  snapshot: Snapshot,
+  refs: ReadonlyMap<string, PlanRef>,
+  context: PageContext,
+): PagePlanDocument[] =>
+  [...refs.entries()].flatMap(([href, ref]) => {
+    const markdown = snapshot.documents.plans[href]
+    if (markdown === undefined || ref.anchor === null) return []
+    const repoPath = resolvePlanPath(context.sprintDirectory, href)
+    const header = readPlanHeader(markdown, context.language, posix.basename(repoPath, '.md'))
+    return [
+      {
+        anchor: ref.anchor,
+        repoPath,
+        title: header.title,
+        status: header.status,
+        progress: progressOf(markdown, context.language) ?? { done: 0, total: 0 },
+        file: ref.file,
+        markdown,
+        chips: extractLinkChips(markdown, context.linkKinds),
+      },
+    ]
+  })
+
+/** The links the page names plans by, in the order the sprint names them: its plans tables first, then the lanes. */
+const hrefsOf = (document: SprintDocument, views: readonly LaneView[]): string[] => [
+  ...document.planTables.flatMap(({ rows }) => rows.flatMap((row) => (row.href ? [row.href] : []))),
+  ...views.flatMap(({ progress }) => progress.steps.flatMap(({ step }) => (step.planHref ? [step.planHref] : []))),
+]
+
+/** The whole sprint as a page: every lane of the table in table order, closed and waiting ones too. */
+export const buildSprintPage = (snapshot: Snapshot, context: PageContext): SprintPage => {
+  const order = snapshot.documents.laneOrder
+  const views = [...snapshot.views].sort(
+    (left, right) => order.indexOf(left.progress.lane.name) - order.indexOf(right.progress.lane.name),
+  )
+  const dependencies = new Map(
+    Object.entries(snapshot.documents.plans).map(([href, text]) => [
+      href,
+      readPhaseDependencies(text, context.language),
+    ]),
+  )
+  const document = readSprintDocument(snapshot.documents.sprint, context.language)
+  const refs = planRefs(snapshot, hrefsOf(document, views), context)
+  const planDocuments = documentsOf(snapshot, refs, context)
+  const anchors = new Map(planDocuments.map((doc) => [doc.repoPath, doc.anchor]))
+  return {
+    title: snapshot.title,
+    generatedAt: context.generatedAt,
+    baseRef: context.baseRef,
+    document,
+    plans: planTablesOf(snapshot, document, refs, context),
+    lanes: views.map((view) => laneOf(view, dependencies, refs)),
+    planDocuments,
+    planned: snapshot.planned.map(({ path, title, phaseIds, done, total }) => ({
+      title,
+      plan: { anchor: anchors.get(path) ?? null, file: fileLink(path, context) },
+      phaseIds,
+      done,
+      total,
+    })),
+    links: {
+      anchors,
+      blobBase: context.repoBlobBase,
+      root: context.root,
+    },
+  }
+}
+
+/** The file the page is written to: `<temporary directory>/jackherd/<board directory>.html`. */
+export const sprintPagePath = (temporaryDirectory: string, sprintDirectory: string): string =>
+  join(temporaryDirectory, 'jackherd', `${posix.basename(sprintDirectory) || 'board'}.html`)