jackherd 1.11.2 → 1.12.0

package/src/plans/next-rows.ts

@@ -1,44 +1,12 @@
 import { sectionLines } from '../plan-format/markdown'
 import { NEXT_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { shortTitle } from './task-name'
-import type { BlockItem } from './waiting-click'
 
-/** A line of the board's next section as the herd shows it. */
-export type NextRow = { text: string }
-
-/** The next block: the section's lines without the ones the for-you block already shows. */
-export type NextBlock = { rows: NextRow[] }
-
-const MAX_NEXT_ROWS = 3
+const MAX_NEXT_LINES = 3
 
 const LIST_LINE = /^(?:\d+[.)]|[-*])\s+(.+)$/
 
-const sameText = (left: string, right: string): boolean => left.trim().toLowerCase() === right.trim().toLowerCase()
-
-/**
- * The next section of the board, up to three list lines in the order written; the parser cuts after three, as the board
- * says. A line equal to one of `shown` (the texts of the for-you block) is left out: it stands above already.
- */
-export const nextBlock = (board: string, language: PlanLanguage, shown: readonly string[]): NextBlock => ({
-  rows: sectionLines(board, NEXT_VOCABULARY[language].heading)
+/** The board's next section, up to three list lines in the order written; the parser cuts after three, as the board says. */
+export const nextLines = (board: string, language: PlanLanguage): string[] =>
+  sectionLines(board, NEXT_VOCABULARY[language].heading)
     .flatMap((line) => LIST_LINE.exec(line.trim())?.[1] ?? [])
-    .slice(0, MAX_NEXT_ROWS)
-    .filter((text) => !shown.some((known) => sameText(known, text)))
-    .map((text) => ({ text })),
-})
-
-const nextKey = ({ text }: NextRow): string => `next>${text}`
-
-/** The rows as the block draws them, numbered; a click on one only expands it. */
-export const nextItems = (rows: readonly NextRow[]): BlockItem[] =>
-  rows.map((row, index) => ({
-    key: nextKey(row),
-    mark: String(index + 1),
-    text: row.text,
-    title: shortTitle(row.text),
-    url: null,
-    ask: null,
-  }))
-
-/** The keys of all rows: what the fold of the block remembers. */
-export const nextKeys = (rows: readonly NextRow[]): string[] => rows.map(nextKey)
+    .slice(0, MAX_NEXT_LINES)

package/src/plans/phase-source.ts

@@ -50,9 +50,14 @@ export const newerPhases = (base: readonly PlanPhase[], copy: readonly PlanPhase
   return [...inBaseOrder, ...copy.filter((phase) => !baseIds.has(phase.id))]
 }
 
-/** A phase read from the worktree is touched when its ticks differ from the base's, or the base lacks it. */
-const markTouched = (phase: PlanPhase, basePhase: PlanPhase | undefined): PlanPhase =>
-  basePhase && sameTicks(phase, basePhase) ? phase : { ...phase, touched: true }
+/**
+ * A phase read from the worktree is touched when its ticks differ from the base's, or the base lacks it; a touched
+ * one is merged as well when the base already carries a tick of it.
+ */
+const markTouched = (phase: PlanPhase, basePhase: PlanPhase | undefined): PlanPhase => {
+  if (basePhase && sameTicks(phase, basePhase)) return phase
+  return basePhase && tickCount(basePhase) > 0 ? { ...phase, touched: true, merged: true } : { ...phase, touched: true }
+}
 
 /**
  * The phases of a plan as the lane sees them: the base ref's phases in their order, each replaced by the

package/src/plans/plan-chips.ts

@@ -51,10 +51,13 @@ export const planAnchorOn = (pagePath: string | null, address: string): string |
 /**
  * What decides whether the written page is out of date: the sprint text, the plan texts and the planned phases.
  * The status of the lanes is left out on purpose, it changes every few seconds and building the page costs
- * seconds; a page older than that says so in its header, and the key `s` writes a fresh one.
+ * seconds; a page older than that says so in its header, and the key `s` writes a fresh one. The texts, megabytes on
+ * a busy board and asked every refresh, are hashed as they are, not escaped into JSON first.
  */
-export const pageKey = ({ documents, planned }: Snapshot): string =>
-  Bun.hash(JSON.stringify([documents, planned])).toString(36)
+export const pageKey = ({ documents: { sprint, plans, ...rest }, planned }: Snapshot): string => {
+  const planHashes = Object.entries(plans).map(([href, text]) => [href, Bun.hash(text).toString(36)])
+  return Bun.hash(JSON.stringify([Bun.hash(sprint).toString(36), planHashes, rest, planned])).toString(36)
+}
 
 /** The sprint page last written, with the key of the plans it was built from. */
 export type KnownPage = WrittenPage & { key: string }

package/src/plans/plan-heads.ts

@@ -8,7 +8,7 @@ export type PlanPullRequest = Pick<PullRequest, 'number' | 'branch' | 'files'>
 export type PlanHead = { number: number; files: readonly string[]; read: BaseReader }
 
 /** Where the herd keeps the fetched heads of open pull requests: its own namespace, apart from branches and remotes. */
-const PULL_HEAD_NAMESPACE = 'refs/jackherd/pr'
+export const PULL_HEAD_NAMESPACE = 'refs/jackherd/pr'
 
 export const pullHeadRef = (number: number): string => `${PULL_HEAD_NAMESPACE}/${number}`
 

package/src/plans/planned.ts

@@ -37,6 +37,8 @@ export type PlannedInput = {
   lanes: readonly PlannedLane[]
   sprintDirectory: string
   language: PlanLanguage
+  /** The phases of a plan's text, by its file; defaults to parsing it, a caller with a plan cache passes its own. */
+  parse?: (markdown: string, path: string) => readonly PlanPhase[]
 }
 
 /** A plan's file, its text and its phases, as one plan row reads them. */
@@ -75,11 +77,12 @@ const plannedPlanOf = ({ path, markdown, phases: all }: PlanRead, language: Plan
 export const plannedPlans = (input: PlannedInput): PlannedPlan[] => {
   const followed = followedPaths(input)
   const seen = new Set<string>()
+  const parse = input.parse ?? ((markdown: string) => parsePlanPhases(markdown, input.language))
   return Object.entries(input.plans).flatMap(([href, markdown]) => {
     const path = resolvePlanPath(input.sprintDirectory, href)
     if (seen.has(path) || followed.has(path)) return []
     seen.add(path)
-    return plannedPlanOf({ path, markdown, phases: parsePlanPhases(markdown, input.language) }, input.language)
+    return plannedPlanOf({ path, markdown, phases: parse(markdown, path) }, input.language)
   })
 }
 

package/src/plans/process-slots.ts

@@ -0,0 +1,36 @@
+/** Runs tasks with at most a fixed number in flight; the others wait in the order they asked. */
+export type ProcessSlots = { run: <T>(task: () => Promise<T>) => Promise<T> }
+
+/**
+ * Slots for child processes. The event loop handles every process that ended in one turn, so dozens started side by
+ * side end as one long block; with `limit` in flight, their ends arrive spread over several turns.
+ */
+export const createProcessSlots = (limit: number): ProcessSlots => {
+  const waiting: (() => void)[] = []
+  let inFlight = 0
+
+  const acquire = (): Promise<void> => {
+    if (inFlight < limit) {
+      inFlight += 1
+      return Promise.resolve()
+    }
+    return new Promise<void>((resolve) => waiting.push(resolve))
+  }
+
+  const release = () => {
+    const next = waiting.shift()
+    if (next) next()
+    else inFlight -= 1
+  }
+
+  const run = async <T>(task: () => Promise<T>): Promise<T> => {
+    await acquire()
+    try {
+      return await task()
+    } finally {
+      release()
+    }
+  }
+
+  return { run }
+}

package/src/plans/pull-requests.ts

@@ -188,8 +188,16 @@ export const pullRequestsByBranch = (pullRequests: readonly PullRequest[]): Map<
     new Map<string, PullRequest[]>(),
   )
 
+const PULL_REQUEST_KEY_PREFIX = 'pr:'
+
 /** The selection key of a pull request row; two parts, so it never equals a three-part phase key. */
-export const pullRequestKey = (number: number): string => `pr:${number}`
+export const pullRequestKey = (number: number): string => `${PULL_REQUEST_KEY_PREFIX}${number}`
+
+/** The number a pull request key names, null for any other key. */
+export const pullRequestNumberOfKey = (key: string): number | null => {
+  const digits = key.startsWith(PULL_REQUEST_KEY_PREFIX) ? key.slice(PULL_REQUEST_KEY_PREFIX.length) : ''
+  return /^\d+$/.test(digits) ? Number(digits) : null
+}
 
 /**
  * The key of a failed test's line under a pull request, by its place in the list: a click unfolds a cut name and folds

package/src/plans/read-cache.ts

@@ -1,8 +1,23 @@
 import type { StatCache } from '../shared/stat-cache'
 import type { TaskSignal } from '../task-signals/types'
+import { type BoardRowsReader, boardRowsReader } from './board-rows'
 import type { PlanCache } from './plan-cache'
+import type { KeptStatus } from './status-pace'
 
-/** What the herd keeps between its reads, so session logs and plans that did not change are not parsed again. */
-export type ReadCache = { signals: StatCache<TaskSignal[]>; plans: PlanCache }
+/**
+ * What the herd keeps between its reads, so session logs, plans and a board that did not change are not parsed
+ * again, and a worktree where nothing moved is not asked `git status` again (`pacedStatus`).
+ */
+export type ReadCache = {
+  signals: StatCache<TaskSignal[]>
+  plans: PlanCache
+  boardRows: BoardRowsReader
+  statuses: Map<string, KeptStatus>
+}
 
-export const newReadCache = (): ReadCache => ({ signals: new Map(), plans: new Map() })
+export const newReadCache = (): ReadCache => ({
+  signals: new Map(),
+  plans: new Map(),
+  boardRows: boardRowsReader(),
+  statuses: new Map(),
+})

package/src/plans/refresh-pace.ts

@@ -0,0 +1,13 @@
+/**
+ * How often the live view reads everything again: at `baseMs` while the screen changes, slower while it does not, up
+ * to `maxMs`. A watched plan file still refreshes at once; the pace only decides how soon an unwatched change (a session
+ * log, an agent's status, git) shows after a quiet spell.
+ */
+export const REFRESH_PACE = { baseMs: 5_000, maxMs: 20_000 } as const
+
+/** The wait before the next refresh after `quietRounds` refreshes in a row wrote nothing: doubled per quiet round, up to `maxMs`. */
+export const refreshDelay = (quietRounds: number): number =>
+  Math.min(REFRESH_PACE.baseMs * 2 ** quietRounds, REFRESH_PACE.maxMs)
+
+/** The quiet rounds after a refresh: one more when it wrote nothing, none when it changed the screen. */
+export const quietRoundsAfter = (quietRounds: number, changed: boolean): number => (changed ? 0 : quietRounds + 1)

package/src/plans/row-focus.ts

@@ -1,7 +1,10 @@
-import { ESC, RESET, stripAnsi, visibleLength } from '../terminal/text'
+import { TONE_ROLE } from '../config/tones'
+import { ESC, FAINT_OFF, FAINT_ON, RESET, stripAnsi, visibleLength } from '../terminal/text'
 import { textWidth } from '../terminal/width'
 import { isChipKey } from './link-chips'
 import type { ClickTarget, MouseEvent, Selection } from './selection'
+import { CHEVRON } from './symbols'
+import { paintOfRole } from './tones'
 import type { BlockHit, BlockRow } from './waiting-click'
 
 /** A clickable row on screen: its key, the screen line (0-based, header lines first) it starts on and how many lines it takes. */
@@ -12,18 +15,34 @@ export const FOCUS_ON = `${ESC}[48;5;238m`
 
 const BACKGROUND_LOST = new RegExp(`${ESC}\\[(?:0|49)?m`, 'g')
 const LEADING_STYLES = new RegExp(`^((?:${ESC}\\[[0-9;]*m)*)(.)`, 'u')
-/** The cells a row's lead may give up for the mark: a blank, the bar of a block, the closed chevron; an open chevron or a tree branch says more. */
-const MARKABLE_LEADS = new Set([' ', '▌', '▸'])
+/** The cells a row's lead may give up for the mark: a blank or the bar of a block; a chevron or a tree branch says more. */
+const MARKABLE_LEADS = new Set([' ', '▌'])
+/** A chevron that leads a row, behind nothing but styles and blanks. */
+const LEADING_CHEVRON = new RegExp(`^((?:${ESC}\\[[0-9;]*m| )*)([${CHEVRON.closed}${CHEVRON.open}])`, 'u')
+
+/** Whether the styles before a point leave the dim on: it was set and neither unset nor reset since. */
+const dimIsOn = (styles: string): boolean =>
+  styles.lastIndexOf(FAINT_ON) > Math.max(styles.lastIndexOf(FAINT_OFF), styles.lastIndexOf(RESET))
+
+/** The chevron of a row in the tone of what runs, the dim around it lifted for it alone. */
+const paintedChevron = (styles: string, chevron: string): string => {
+  const dimmed = dimIsOn(styles)
+  return `${styles}${dimmed ? FAINT_OFF : ''}${paintOfRole(TONE_ROLE.running)(chevron)}${dimmed ? FAINT_ON : ''}`
+}
 
-const markedLead = (line: string): string =>
-  line.replace(LEADING_STYLES, (whole, styles: string, lead: string) =>
+/** The row's chevron painted, which says the row opens; else the `❯` on the blank or bar that leads it. */
+const markedLead = (line: string): string => {
+  if (LEADING_CHEVRON.test(line))
+    return line.replace(LEADING_CHEVRON, (_whole, styles: string, chevron: string) => paintedChevron(styles, chevron))
+  return line.replace(LEADING_STYLES, (whole, styles: string, lead: string) =>
     MARKABLE_LEADS.has(lead) ? `${styles}${FOCUS_MARK}` : whole,
   )
+}
 
 /**
  * A row under the mouse or the selection: a light background across `width` cells, and, on the first line of the row
- * (`marked`), the `❯` in place of the bar, blank or closed chevron that leads it. The background is laid again after
- * every reset inside the line, so styled text and buttons keep it.
+ * (`marked`), its leading chevron in the tone of what runs, or the `❯` in place of the bar or blank that leads it. The
+ * background is laid again after every reset inside the line, so styled text and buttons keep it.
  */
 export const focusLine = (line: string, width: number, marked: boolean): string => {
   const shown = marked ? markedLead(line) : line
@@ -38,6 +57,14 @@ export const focusHitAt = (hits: readonly FocusHit[], line: number): FocusHit |
 /** The screen a motion report is looked up on: header lines, the body's rows and how far it is scrolled. */
 export type HoverFrame = { headerRows: number; bodyRows: number; top: number }
 
+/** A drawn screen as the mouse sees it: its lines, the rows on it and how the body is scrolled. */
+export type HoverScreen = {
+  header: readonly string[]
+  bodyLines: readonly string[]
+  focusHits: readonly FocusHit[]
+  frame: HoverFrame
+}
+
 /** The screen line (0-based, header first, the body unscrolled) under a motion report; null in the footer. */
 export const lineIndexAt = ({ row }: MouseEvent, { headerRows, bodyRows, top }: HoverFrame): number | null => {
   const line = row - 1
@@ -98,14 +125,53 @@ export const boldBracketAt = (line: string, from: number): string => {
 /** The key of the hit of a line that holds links but is no row of its own: it is marked by the mouse only. */
 export const LINKS_KEY_PREFIX = 'links@'
 
-/** The selection with the row under the mouse and the button in it set; the selection itself while both are the same. */
-export const withHovered = (selection: Selection, key: string | null, from: number | null = null): Selection =>
-  (selection.hovered ?? null) === key && (selection.hoveredFrom ?? null) === from
+const isLinksKey = (key: string | null | undefined): boolean => key?.startsWith(LINKS_KEY_PREFIX) === true
+
+/** Whether the mouse moving onto `key` takes the selection: a row does, a line of links (no row of its own) and none do not. */
+const takesSelection = (key: string | null): key is string => key !== null && !isLinksKey(key)
+
+/** Whether the selected row is the one the mouse chose, not one the arrows moved to. */
+const isMouseChosen = ({ selected, hovered }: Selection): boolean => (hovered ?? null) !== null && hovered === selected
+
+/**
+ * The selection with the row under the mouse and the button in it set; the row also becomes the selected one, so
+ * the mouse and the arrows share one focus. When the mouse leaves for a line without a row (a blank line, a head, a
+ * text, a line of links), the row it chose is no longer selected; a row the arrows selected stays. The selection
+ * itself while nothing changes.
+ */
+export const withHovered = (selection: Selection, key: string | null, from: number | null = null): Selection => {
+  const kept = isMouseChosen(selection) ? null : selection.selected
+  const selected = takesSelection(key) ? key : kept
+  const same =
+    (selection.hovered ?? null) === key && (selection.hoveredFrom ?? null) === from && selection.selected === selected
+  return same ? selection : { ...selection, selected, hovered: key, hoveredFrom: from }
+}
+
+/** The selection without the row under the mouse: a key press hands the focus back to the arrows. */
+export const withoutHover = (selection: Selection): Selection =>
+  (selection.hovered ?? null) === null && (selection.hoveredFrom ?? null) === null
     ? selection
-    : { ...selection, hovered: key, hoveredFrom: from }
+    : { ...selection, hovered: null, hoveredFrom: null }
+
+/** The selection with the row and the square-bracket button under the mouse, as `withHovered` sets them. */
+export const hoveredSelection = (selection: Selection, screen: HoverScreen, mouse: MouseEvent): Selection => {
+  const key = hoveredKeyAt(screen.focusHits, mouse, screen.frame)
+  const line = lineIndexAt(mouse, screen.frame)
+  const text = line === null ? '' : (screen.header[line] ?? screen.bodyLines[line - screen.frame.headerRows] ?? '')
+  return withHovered(selection, key, key === null ? null : bracketAt(stripAnsi(text), mouse.column - 1))
+}
+
+/**
+ * The selection after a new frame under a mouse that did not move (`mouse` is its last report, null before the first):
+ * a layout that moved another row under it gives that row the focus. Only while the mouse has the focus; after a key
+ * press the arrows keep it. The selection itself when nothing changes.
+ */
+export const rehovered = (selection: Selection, screen: HoverScreen, mouse: MouseEvent | null): Selection =>
+  mouse === null || (selection.hovered ?? null) === null ? selection : hoveredSelection(selection, screen, mouse)
 
-/** Whether a row is the selected one or the one under the mouse. */
-export const isFocused = ({ selected, hovered }: Selection, key: string): boolean => key === selected || key === hovered
+/** Whether a row has the focus: the selected one, unless the mouse is on a line of links, which then has it alone. */
+export const isFocused = ({ selected, hovered }: Selection, key: string): boolean =>
+  key === selected && !isLinksKey(hovered)
 
 /** Whether the buttons of a row are all bold: it is the row the arrows selected, and the mouse is not on it. */
 export const buttonsAllBold = ({ selected, hovered }: Selection, key: string): boolean =>
@@ -115,14 +181,19 @@ export const buttonsAllBold = ({ selected, hovered }: Selection, key: string): b
 export const blockRowByKey = (blocks: readonly (BlockHit | null)[], key: string): BlockRow | null =>
   blocks.flatMap((block) => block?.rows ?? []).find((row) => row.key === key) ?? null
 
-/** The rows of a block on top of the herd, from the screen line of its first row; none while the block is not drawn or folded. */
+/**
+ * The head of a block on top of the herd, when it can open, then its rows from the screen line of its first row; no
+ * rows while the block is folded, nothing while it is not drawn.
+ */
 export const focusHitsOfBlock = (block: BlockHit | null): FocusHit[] => {
   let line = block?.firstLine ?? 0
-  return (block?.rows ?? []).map((row) => {
+  const head = block?.headKey ? [{ key: block.headKey, line: line - 1, lines: 1 }] : []
+  const rows = (block?.rows ?? []).map((row) => {
     const hit = { key: row.key, line, lines: row.lines.length }
     line += row.lines.length
     return hit
   })
+  return [...head, ...rows]
 }
 
 /**