jackherd 1.7.0 → 1.8.0

package/src/plans/frame.ts

@@ -0,0 +1,99 @@
+import { BAR_SEGMENT, INVERSE_ON, paint, RESET, stripAnsi, visibleLength } from '../terminal/text'
+import type { ClickTarget, Selection } from './selection'
+
+/**
+ * The lines of a frame, the line holding the selected row, a phase or a task (-1 when none), so the window can
+ * follow it, and the spans a click expands or closes.
+ */
+export type Frame = { lines: string[]; cursorLine: number; targets: ClickTarget[] }
+
+/** What goes in front of a frame's lines: `first` on its first line, `rest` on the others, both drawn in `style`. */
+export type Lead = { first: string; rest: string; style: (text: string) => string }
+
+/** The tree lines: a branch to a sibling that has more below it, the last branch, and what carries on beside them. */
+export const TREE = { branch: '├─ ', last: '└─ ', pipe: '│  ', gap: '   ', trunk: '│' } as const
+const TREE_GUTTER = TREE.branch.length
+
+export const textFrame = (lines: string[]): Frame => ({ lines, cursorLine: -1, targets: [] })
+
+/** Stacks frames, moving each one's cursor line and click targets below the frames before it. */
+export const joinFrames = (frames: Frame[]): Frame =>
+  frames.reduce<Frame>((joined, frame) => {
+    const offset = joined.lines.length
+    return {
+      lines: [...joined.lines, ...frame.lines],
+      cursorLine: frame.cursorLine === -1 ? joined.cursorLine : offset + frame.cursorLine,
+      targets: [...joined.targets, ...frame.targets.map((target) => ({ ...target, line: offset + target.line }))],
+    }
+  }, textFrame([]))
+
+/**
+ * A frame moved right by its lead, as many cells as `first` is wide; an empty line takes the lead without its
+ * trailing blanks. A click target over the whole line keeps the left edge and takes the lead in.
+ */
+export const prefixed = (frame: Frame, { first, rest, style }: Lead): Frame => {
+  const gutter = visibleLength(first)
+  return {
+    lines: frame.lines.map((line, index) => {
+      const lead = index === 0 ? first : rest
+      return line === '' ? style(lead.trimEnd()) : `${style(lead)}${line}`
+    }),
+    cursorLine: frame.cursorLine,
+    targets: frame.targets.map((target) => ({
+      ...target,
+      from: target.wholeLine ? 0 : target.from + gutter,
+      to: target.to + gutter,
+    })),
+  }
+}
+
+/** The context of the children of a node: the pane minus the tree lines in front of them. */
+export const deeper = <Context extends { width: number }>(context: Context): Context => ({
+  ...context,
+  width: Math.max(context.width - TREE_GUTTER, 1),
+})
+
+const branches = (children: Frame[]): Frame[] => {
+  const present = children.filter((child) => child.lines.length > 0)
+  return present.map((child, index) => {
+    const last = index === present.length - 1
+    return prefixed(child, {
+      first: last ? TREE.last : TREE.branch,
+      rest: last ? TREE.gap : TREE.pipe,
+      style: paint.dim,
+    })
+  })
+}
+
+/**
+ * The children of a node as a tree: each child's first line behind a branch, the last behind the closing one, the
+ * lines of a child after its first beside the trunk. The caller has drawn the children `TREE_GUTTER` narrower
+ * (`deeper`); a child without lines leaves no branch.
+ */
+export const nest = (children: Frame[]): Frame => joinFrames(branches(children))
+
+/**
+ * A row drawn inverse across the pane. A progress bar inside it is switched back to normal video: inverted,
+ * its filled and empty blocks would trade places with the background and the bar would be unreadable.
+ */
+const highlight = (line: string, width: number): string => {
+  const bars = line.match(BAR_SEGMENT) ?? []
+  const texts = line.split(BAR_SEGMENT).map(stripAnsi)
+  const body = texts.map((text, index) => `${text}${bars[index] ? `${bars[index]}${INVERSE_ON}` : ''}`).join('')
+  return `${INVERSE_ON}${body}${' '.repeat(Math.max(width - visibleLength(line), 0))}${RESET}`
+}
+
+/** A selectable row: drawn inverse when selected, clickable across the pane on every line, `below` follows unselectable. */
+export const rowFrame = (
+  key: string,
+  rows: string[],
+  below: string[],
+  { state, width }: { state: Selection; width: number },
+): Frame => {
+  const selected = state.selected === key
+  return {
+    lines: [...(selected ? rows.map((row) => highlight(row, width)) : rows), ...below],
+    cursorLine: selected ? 0 : -1,
+    targets: rows.map((_, line) => ({ line, from: 0, to: width, key, wholeLine: true as const })),
+  }
+}

package/src/plans/git.ts

@@ -14,6 +14,14 @@ const git = (cwd: string, args: string[]): string | null => {
   return result.exitCode === 0 ? result.stdout.toString().trim() : null
 }
 
+/** What git says about a file in a checkout: its porcelain status and the short commit that last changed it. */
+export type FileGitFacts = { status: string | null; commit: string | null }
+
+export const fileGitFacts = (root: string, path: string): FileGitFacts => ({
+  status: git(root, ['status', '--porcelain', '--', path]),
+  commit: git(root, ['log', '-1', '--format=%h', '--', path]),
+})
+
 /** The text of `path` at `ref`, or null when the ref or the file does not exist there. */
 export const showAtRef = (root: string, ref: string, path: string): string | null => {
   const result = Bun.spawnSync(['git', '-C', root, 'show', `${ref}:${path}`], { stdout: 'pipe', stderr: 'pipe' })

package/src/plans/herd-memory.ts

@@ -0,0 +1,107 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { repositoryKey } from '../watch/watcher-lock'
+import type { LaneMemory } from './current-phase'
+
+const DIRECTORY_PREFIX = 'jackherd-herd'
+const MEMORY_FILE = 'herd-memory.json'
+const PRIVATE_DIRECTORY = 0o700
+const PRIVATE_FILE = 0o600
+
+const phaseRef = z.object({ planHref: z.string(), phaseId: z.string() })
+
+const laneMemory = z.object({
+  ticks: z.record(z.string(), z.record(z.string(), z.string())),
+  moved: phaseRef.nullable(),
+  row: z.string(),
+  activity: z.record(z.string(), z.number()).optional(),
+})
+
+const memoryFile = z.record(z.string(), laneMemory)
+
+/**
+ * The lanes' memories as a file holds them; nothing for a missing, broken or foreign file, so the herd then starts
+ * as on its first read and no phase gets a time from it.
+ */
+export const parseLaneMemories = (text: string | null): Map<string, LaneMemory> => {
+  if (text === null) return new Map()
+  try {
+    const parsed = memoryFile.safeParse(JSON.parse(text))
+    return parsed.success ? new Map(Object.entries(parsed.data)) : new Map()
+  } catch {
+    return new Map()
+  }
+}
+
+/**
+ * What a herd that read `lanes` writes back: the stored memories with those lanes replaced by its own, a lane it read
+ * but no longer remembers dropped; other herds' lanes (another pane, another `--lane`) stay as they were.
+ */
+export const mergedMemories = (
+  stored: ReadonlyMap<string, LaneMemory>,
+  own: ReadonlyMap<string, LaneMemory>,
+  lanes: readonly string[],
+): Record<string, LaneMemory> => {
+  const read = new Set(lanes)
+  const kept = [...stored].filter(([lane]) => !read.has(lane))
+  const fresh = [...own].filter(([lane]) => read.has(lane))
+  return Object.fromEntries([...kept, ...fresh])
+}
+
+/**
+ * Where the herds of the repository at `root` keep what they saw of each lane, one directory per user and
+ * repository like the watcher's, so a `--once` run and a restarted herd know when a phase last moved.
+ */
+const herdMemoryDirectory = (root: string): string =>
+  join(tmpdir(), `${DIRECTORY_PREFIX}-${process.getuid?.() ?? 'user'}`, repositoryKey(root))
+
+export const memoryFileOf = (directory: string): string => join(directory, MEMORY_FILE)
+
+const readText = (file: string): string | null => {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+export const readLaneMemories = (directory: string): Map<string, LaneMemory> =>
+  parseLaneMemories(readText(memoryFileOf(directory)))
+
+/**
+ * Writes the memories of `lanes` into the file of `directory`, beside what other herds keep there; readable by the
+ * user only, and replaced in one step so a herd reading at the same time never sees half a file.
+ */
+export const writeLaneMemories = (
+  directory: string,
+  memories: ReadonlyMap<string, LaneMemory>,
+  lanes: readonly string[],
+): void => {
+  mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
+  const file = memoryFileOf(directory)
+  const merged = mergedMemories(readLaneMemories(directory), memories, lanes)
+  const partial = `${file}.${process.pid}`
+  writeFileSync(partial, JSON.stringify(merged), { mode: PRIVATE_FILE })
+  renameSync(partial, file)
+}
+
+/** The memories the herds of the repository at `root` kept. */
+export const recallLanes = (root: string): Map<string, LaneMemory> => readLaneMemories(herdMemoryDirectory(root))
+
+/**
+ * Keeps the memories of `lanes` for the next herd. A memory that cannot be written costs only the times of the next
+ * run, which then starts as on its first read, so the view goes on without it.
+ */
+export const rememberLanes = (
+  root: string,
+  memories: ReadonlyMap<string, LaneMemory>,
+  lanes: readonly string[],
+): void => {
+  try {
+    writeLaneMemories(herdMemoryDirectory(root), memories, lanes)
+  } catch {
+    return
+  }
+}

package/src/plans/lane-plans.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { type PlansByHref, parsePlanPhases, resolvePlanPath, type SprintLane } from '../plan-format'
 import type { BaseReader } from './git'
@@ -52,13 +52,14 @@ export const laneWorkOf = (worktree: string, status: { ahead: number | null; dir
  * The plans of a lane. The base ref is the truth; while the lane has work of its own in its worktree, the phases
  * its rows name, and those new there or ticked further, come from the worktree (`mergePlanPhases`). A plan the base ref lacks is read from the lane's worktree, else from the main
  * checkout (a repository that ignores `docs/` keeps plan and board only there). `files` are the plan files to
- * watch for changes.
+ * watch for changes, `modified` when each was last written, by plan link (`nextActivity` bounds a movement by it).
  */
 export const readPlans = async (lane: SprintLane, sources: PlanSources, work: LaneWork, fallbacks: Fallbacks) => {
   const { root, settings, sprintDirectory } = sources
   const plans: PlansByHref = {}
   const files: string[] = []
   const texts: Record<string, string> = {}
+  const modified: Record<string, number> = {}
   for (const href of new Set(lane.steps.flatMap((step) => (step.planHref ? [step.planHref] : [])))) {
     const path = resolvePlanPath(sprintDirectory, href)
     const worktreeFile = work.worktree ? join(work.worktree, path) : null
@@ -75,6 +76,7 @@ export const readPlans = async (lane: SprintLane, sources: PlanSources, work: La
     )
     files.push(file)
     texts[href] = text
+    if (existsSync(file)) modified[href] = statSync(file).mtimeMs
   }
-  return { plans, files, texts }
+  return { plans, files, texts, modified }
 }

package/src/plans/lane-summary.ts

@@ -0,0 +1,222 @@
+import {
+  isPhaseFinished,
+  isPhaseOpen,
+  isTickedUnmerged,
+  type LaneProgress,
+  type PhaseProgress,
+  type PlanPhase,
+  type PlansByHref,
+  parseDependencyTable,
+  phaseProgress,
+  phaseWaves,
+} from '../plan-format'
+import type { PlanLanguage } from '../vocabulary'
+import { type ActivityTimes, activityKey } from './current-phase'
+import { currentTasks, type TaskSignal } from './current-task'
+
+/**
+ * A phase the lane works on now: an open one whose ticks or task lines moved less than `STALE_ACTIVITY_MINUTES` ago.
+ * `stepIndex` is the newest step of the lane that shows it, null for a phase no step shows; `minutesAgo` the whole
+ * minutes since that movement.
+ */
+export type ActivePhase = {
+  phase: PhaseProgress
+  stepIndex: number | null
+  minutesAgo: number
+  /** The index of the task the phase is on in its checkboxes (`currentTasks`); null when none is open. */
+  taskIndex: number | null
+}
+
+/** The phases that come next: the open ones of the next wave, `wave` its 1-based number, null without a dependency table. */
+export type NextPhases = { wave: number | null; phaseIds: string[] }
+
+/** Open phases after the next ones; `planTitle` is null for the lane's current plan, the board's title for another. */
+export type LaterPhases = { planTitle: string | null; phaseIds: string[] }
+
+export type FinishedPhase = { id: string; unmerged: boolean }
+
+/** A phase the lane's board rows name that has nothing to run: `missing` when the plan lacks it, else it has no checkbox. */
+export type UnwrittenPhase = { id: string; missing: boolean }
+
+/** Checkboxes and phases over every plan of the lane, a phase counted when it has a checkbox. */
+export type PlanTally = { done: number; total: number; phasesDone: number; phases: number }
+
+/** A lane as the herd sums it up: what runs now, what comes next and after, what is finished, and how far it is. */
+export type LaneSummary = {
+  /** The running phases, the one moved last first. */
+  active: ActivePhase[]
+  /** The open phase of the current plan moved last, at any age; null while none has a time. */
+  latest: PhaseProgress | null
+  next: NextPhases | null
+  later: LaterPhases[]
+  finished: FinishedPhase[]
+  unwritten: UnwrittenPhase[]
+  tally: PlanTally
+}
+
+/**
+ * `phases` are the lane's plans as it reads them (the base merged with its worktree), `texts` their texts for the
+ * dependency tables; a plan missing from `phases` falls back to the phases the lane's steps show.
+ */
+export type SummaryInput = {
+  progress: LaneProgress
+  phases: Readonly<PlansByHref>
+  texts: Readonly<Record<string, string>>
+  activity: ActivityTimes
+  /** The language the plans were written in, for reading their dependency tables; the herd's words are English. */
+  language: PlanLanguage
+  /** Hints at the task a phase is on, by phase id; none when absent, and no source writes one yet. */
+  signals?: readonly TaskSignal[]
+}
+
+/** Minutes without a tick or a new task line after which a phase no longer runs. */
+export const STALE_ACTIVITY_MINUTES = 20
+
+const MINUTE = 60_000
+
+const isWritten = ({ total }: PhaseProgress): boolean => total > 0
+
+const planHrefs = ({ steps }: LaneProgress): string[] => [
+  ...new Set(steps.flatMap(({ step }) => (step.planHref ? [step.planHref] : []))),
+]
+
+/** The plan of the lane's current phase, else its first plan. */
+const focusHref = (progress: LaneProgress): string | null => {
+  const current = progress.current ? progress.steps[progress.current.stepIndex]?.step.planHref : null
+  return current ?? planHrefs(progress)[0] ?? null
+}
+
+/** The phases the steps on `href` show, each once, when the plan itself was not read. */
+const stepPhases = ({ steps }: LaneProgress, href: string): PhaseProgress[] => {
+  const shown = steps.filter(({ step }) => step.planHref === href).flatMap(({ phases }) => phases)
+  return shown.filter((phase, index) => shown.findIndex(({ id }) => id === phase.id) === index)
+}
+
+const phasesOf = (input: SummaryInput, href: string): PhaseProgress[] => {
+  const plan: readonly PlanPhase[] | undefined = input.phases[href]
+  return plan ? plan.map(({ id }) => phaseProgress(plan, id)) : stepPhases(input.progress, href)
+}
+
+const newestStepShowing = ({ steps }: LaneProgress, href: string, id: string): number | null => {
+  const index = steps
+    .map(({ step, phases }) => step.planHref === href && phases.some((phase) => phase.id === id))
+    .lastIndexOf(true)
+  return index === -1 ? null : index
+}
+
+type TimedPhase = { phase: PhaseProgress; minutesAgo: number }
+
+/** The open phases with a time of their last movement, the one moved last first; a phase without a time is absent. */
+const timedPhases = (input: SummaryInput, href: string, phases: PhaseProgress[], now: number): TimedPhase[] =>
+  phases
+    .filter(isPhaseOpen)
+    .flatMap((phase) => {
+      const at = input.activity[activityKey(href, phase.id)]
+      return at === undefined ? [] : [{ phase, minutesAgo: Math.max(Math.floor((now - at) / MINUTE), 0) }]
+    })
+    .sort((first, second) => first.minutesAgo - second.minutesAgo)
+
+/** The timed phases that moved less than `STALE_ACTIVITY_MINUTES` ago, each with the task it is on. */
+const activeOf = (input: SummaryInput, href: string, timed: TimedPhase[], now: number): ActivePhase[] => {
+  const running = timed.filter(({ minutesAgo }) => minutesAgo < STALE_ACTIVITY_MINUTES)
+  const tasks = currentTasks(
+    running.map(({ phase }) => phase),
+    input.signals ?? [],
+    now,
+    STALE_ACTIVITY_MINUTES * MINUTE,
+  )
+  return running.map(({ phase, minutesAgo }) => ({
+    phase,
+    stepIndex: newestStepShowing(input.progress, href, phase.id),
+    minutesAgo,
+    taskIndex: tasks.get(phase.id) ?? null,
+  }))
+}
+
+/**
+ * The open phases of the first wave that holds one not running; without a dependency table, phases run one after the
+ * other and the next is the first open one not running. Null when nothing is left, or no wave holds what is left.
+ */
+const nextOf = (
+  input: SummaryInput,
+  href: string,
+  phases: PhaseProgress[],
+  running: ReadonlySet<string>,
+): NextPhases | null => {
+  const waiting = phases.filter((phase) => isPhaseOpen(phase) && !running.has(phase.id)).map(({ id }) => id)
+  const text = input.texts[href]
+  const rows = text === undefined ? null : parseDependencyTable(text, input.language)
+  if (rows === null) return waiting.length > 0 ? { wave: null, phaseIds: [waiting[0]] } : null
+  const done = new Set(phases.filter(isPhaseFinished).map(({ id }) => id))
+  const waves = phaseWaves(rows, done)
+  const index = waves.findIndex((wave) => wave.some((id) => waiting.includes(id)))
+  return index === -1 ? null : { wave: index + 1, phaseIds: waves[index].filter((id) => waiting.includes(id)) }
+}
+
+const tallyOf = (phases: PhaseProgress[]): PlanTally => ({
+  done: phases.reduce((sum, phase) => sum + phase.done, 0),
+  total: phases.reduce((sum, phase) => sum + phase.total, 0),
+  phasesDone: phases.filter(isPhaseFinished).length,
+  phases: phases.filter(isWritten).length,
+})
+
+const titleOf = ({ steps }: LaneProgress, href: string): string =>
+  steps.find(({ step }) => step.planHref === href)?.step.planTitle ?? href
+
+/** The open phases of the lane's other plans, each plan by its title. */
+const otherPlans = (input: SummaryInput, hrefs: string[]): LaterPhases[] =>
+  hrefs.flatMap((href) => {
+    const open = phasesOf(input, href).filter(isPhaseOpen)
+    return open.length > 0 ? [{ planTitle: titleOf(input.progress, href), phaseIds: open.map(({ id }) => id) }] : []
+  })
+
+/** The open phases of the current plan that neither run nor come next, then the open phases of the lane's other plans. */
+const laterOf = (
+  input: SummaryInput,
+  href: string,
+  phases: PhaseProgress[],
+  upcoming: ReadonlySet<string>,
+): LaterPhases[] => {
+  const waiting = phases
+    .filter((phase) => isPhaseOpen(phase) && !upcoming.has(phase.id))
+    .map(({ id }) => id)
+    .sort((first, second) => first.localeCompare(second, undefined, { numeric: true }))
+  const others = otherPlans(
+    input,
+    planHrefs(input.progress).filter((each) => each !== href),
+  )
+  return [...(waiting.length > 0 ? [{ planTitle: null, phaseIds: waiting }] : []), ...others]
+}
+
+/** The finished phases of the current plan, each marked while its ticks are not merged. */
+const finishedOf = (phases: PhaseProgress[]): FinishedPhase[] =>
+  phases.filter(isPhaseFinished).map((phase) => ({ id: phase.id, unmerged: isTickedUnmerged(phase) }))
+
+/**
+ * The lane summed up over its plans at `now`: the open phases running in its current plan (moved less than
+ * `STALE_ACTIVITY_MINUTES` ago; a phase without a time of its last movement never runs), the open phase moved last,
+ * the next wave's open phases, the other open phases, the finished ones (marked when not merged yet), the phases its
+ * rows name with nothing to run, and the tally over every plan of the lane. A phase ticked to the end, review gate
+ * included, is finished, never running.
+ */
+export const laneSummary = (input: SummaryInput, now: number): LaneSummary => {
+  const href = focusHref(input.progress)
+  const tally = tallyOf(planHrefs(input.progress).flatMap((each) => phasesOf(input, each)))
+  if (href === null) return { active: [], latest: null, next: null, later: [], finished: [], unwritten: [], tally }
+  const phases = phasesOf(input, href)
+  const timed = timedPhases(input, href, phases, now)
+  const active = activeOf(input, href, timed, now)
+  const running = new Set(active.map(({ phase }) => phase.id))
+  const next = nextOf(input, href, phases, running)
+  return {
+    active,
+    latest: timed[0]?.phase ?? null,
+    next,
+    later: laterOf(input, href, phases, new Set([...running, ...(next?.phaseIds ?? [])])),
+    finished: finishedOf(phases),
+    unwritten: stepPhases(input.progress, href)
+      .filter((phase) => !isWritten(phase))
+      .map(({ id, title }) => ({ id, missing: title === null })),
+    tally,
+  }
+}

package/src/plans/layout-phase.ts

@@ -0,0 +1,148 @@
+import type { ChecklistItem, DeferredItem, LaneProgress, PhaseProgress } from '../plan-format'
+import { onlyDocumentationOpen, phaseLabel } from '../plan-format'
+import { fit, padVisible, paint, wrap } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+import type { WatchBadges } from '../watch/plan-badges'
+import { type Frame, rowFrame, textFrame } from './frame'
+import type { LaneTickets } from './lane-tickets'
+import type { LinkChip } from './link-chips'
+import type { PhaseModel } from './phase-models'
+import { itemKey, type Selection, tickedKey } from './selection'
+import { chevronOf, MODEL_MARK, PHASE_COUNT, PHASE_STATE, type PhaseState, phaseStateOf } from './symbols'
+import { type BadgeTexts, TEXTS } from './texts'
+
+/** What every block of one lane is drawn with. */
+export type LaneContext = {
+  progress: LaneProgress
+  state: Selection
+  width: number
+  chips: Record<string, LinkChip[]>
+  badges: WatchBadges
+  badgeTexts: BadgeTexts
+  /** The lane's tickets for the plan block that shows them, the first; null in every other block. */
+  tickets: LaneTickets | null
+  /** The model each phase ran on, by `phaseModelKey`. */
+  models: Record<string, PhaseModel>
+}
+
+export const ACTIVE_MARK = '▶'
+export const DEFERRED_MARK = '→'
+export const COLUMN_SEPARATOR = '  '
+export const MIN_TITLE_WIDTH = 8
+
+/** Places on each side of the slash of a count: `  9/9  `, ` 15/15 `, `123/456`. */
+const COUNT_PLACES = 3
+/** The cells before a count: `◐`, `✓`, `?`, `–` or nothing, padded so every slash on screen is in one column. */
+const COUNT_MARK_WIDTH = 2
+const BLANK_COUNT = ' '.repeat(2 * COUNT_PLACES + 1)
+const COUNT_CELL_WIDTH = COUNT_MARK_WIDTH + 1 + BLANK_COUNT.length
+const MARKDOWN_MARKS = /\*\*|`/g
+
+const PHASE_PAINT: Record<PhaseState, (count: string) => string> = {
+  [PHASE_STATE.missing]: paint.dim,
+  [PHASE_STATE.empty]: paint.dim,
+  [PHASE_STATE.all]: paint.green,
+  [PHASE_STATE.open]: (count) => count,
+}
+
+const PHASE_MARK: Record<PhaseState, string> = {
+  [PHASE_STATE.missing]: PHASE_COUNT.missing,
+  [PHASE_STATE.empty]: PHASE_COUNT.empty,
+  [PHASE_STATE.all]: '',
+  [PHASE_STATE.open]: '',
+}
+
+export const plain = (text: string): string => text.replace(MARKDOWN_MARKS, '')
+
+export const countText = (done: number, total: number): string =>
+  `${String(done).padStart(COUNT_PLACES)}/${String(total).padEnd(COUNT_PLACES)}`
+
+/** Mark and count in one fixed-width cell at the right edge, the same for the lane, phase and planned rows. */
+export const countCell = (mark: string, count: string): string => `${padVisible(mark, COUNT_MARK_WIDTH)} ${count}`
+
+/** A word in place of a count, right-aligned in the width of the count cell like `n/m`. */
+const wordCell = (word: string): string => `${' '.repeat(Math.max(COUNT_CELL_WIDTH - textWidth(word), 0))}${word}`
+
+/** The count cell of a phase row at the right edge; the current phase is bold yellow. A phase lacking only the documentation box says so instead of a count. */
+export const phaseCountCell = (phase: PhaseProgress, current: boolean): string => {
+  const state = phaseStateOf(phase)
+  if (state === PHASE_STATE.open && onlyDocumentationOpen(phase)) {
+    const cell = wordCell(TEXTS.allButDocs)
+    return current ? paint.bold(paint.yellow(cell)) : paint.green(cell)
+  }
+  const hasCount = state === PHASE_STATE.open || state === PHASE_STATE.all
+  const cell = countCell(PHASE_MARK[state], hasCount ? countText(phase.done, phase.total) : BLANK_COUNT)
+  return current ? paint.bold(paint.yellow(cell)) : PHASE_PAINT[state](cell)
+}
+
+const familyLabel = (family: string): string => `${family.charAt(0).toUpperCase()}${family.slice(1)}`
+
+/**
+ * The model the phase's subagent last ran on, only where it differs from the plan's recommendation: `Sonnet ≠ Opus`
+ * in amber; empty without a record, without a recommendation, or when it fits.
+ */
+export const modelMark = (model: PhaseModel | undefined): string =>
+  model?.recommended && model.fits === false
+    ? paint.yellow(`${familyLabel(model.used)} ${MODEL_MARK.differs} ${familyLabel(model.recommended)}`)
+    : ''
+
+/** `text` wrapped beside a one-cell `mark`, each line in `style`; follow-up lines indent under the text. */
+const markedLines = (text: string, mark: string, style: (line: string) => string, width: number): string[] =>
+  wrap(plain(text), Math.max(width - 2, 1)).map((line, index) => `${index > 0 ? ' ' : mark} ${style(line)}`)
+
+/** The mark and the text style of a task: a ticked one green and dim, the one being worked on yellow and bold. */
+const taskLook = ({ done }: ChecklistItem, active: boolean): { mark: string; style: (line: string) => string } => {
+  if (active) return { mark: paint.yellow(ACTIVE_MARK), style: paint.bold }
+  return done ? { mark: paint.green('☑'), style: paint.dim } : { mark: '☐', style: (line) => line }
+}
+
+/** A closed task as one row, cut at the pane's edge with `…`. */
+const closedTaskRow = (item: ChecklistItem, active: boolean, width: number): string[] => {
+  const { mark, style } = taskLook(item, active)
+  return [fit(`${mark} ${style(plain(item.text))}`, width)]
+}
+
+/** An open task as rows: its whole text wrapped. */
+const openTaskRows = (item: ChecklistItem, active: boolean, width: number): string[] => {
+  const { mark, style } = taskLook(item, active)
+  return markedLines(item.text, mark, style, width)
+}
+
+/** A task as a selectable row under its `key`: clickable across every line it takes, the cursor on its first. */
+export const taskFrame = (key: string, rows: string[], context: Pick<LaneContext, 'state' | 'width'>): Frame =>
+  rowFrame(key, rows, [], context)
+
+/** A checkbox moved to another phase, dim: `→ P9 <text>`. */
+const deferredRow = ({ text, target }: DeferredItem, width: number): string =>
+  fit(paint.dim(`${DEFERRED_MARK} ${phaseLabel(target)} ${plain(text)}`), width)
+
+const tickedSummaryFrame = (count: number, phaseRowKey: string, width: number): Frame => ({
+  lines: [fit(paint.dim(`${chevronOf(false)} ${TEXTS.tickedSummary(count)}`), width)],
+  cursorLine: -1,
+  targets: [{ line: 0, from: 0, to: width, key: tickedKey(phaseRowKey), wholeLine: true }],
+})
+
+/**
+ * The children of an open phase, one frame per task: open ones first, `active` marked among them, then the ones
+ * deferred to another phase, then the ticked ones listed or summed up.
+ */
+export const phaseChildren = (
+  context: LaneContext,
+  phaseRowKey: string,
+  phase: PhaseProgress,
+  active: ChecklistItem | null,
+): Frame[] => {
+  const { state, width } = context
+  const frameOf = (item: ChecklistItem, index: number): Frame => {
+    const key = itemKey(phaseRowKey, index)
+    const isActive = item === active
+    const rows = state.expanded.has(key) ? openTaskRows(item, isActive, width) : closedTaskRow(item, isActive, width)
+    return taskFrame(key, rows, context)
+  }
+  const framesWhere = (done: boolean): Frame[] =>
+    phase.items.flatMap((item, index) => (item.done === done ? [frameOf(item, index)] : []))
+  const tickedCount = phase.items.filter((item) => item.done).length
+  const summary = tickedCount > 0 ? [tickedSummaryFrame(tickedCount, phaseRowKey, width)] : []
+  const deferred = (phase.deferred ?? []).map((item) => textFrame([deferredRow(item, width)]))
+  return [...framesWhere(false), ...deferred, ...(state.showDone ? framesWhere(true) : summary)]
+}