jackherd 1.6.0 → 1.7.0

package/src/plans/live.ts

@@ -3,6 +3,7 @@ import { dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { openInBrowser } from '../terminal/open'
+import type { LaneMemory } from './current-phase'
 import { errorText } from './error-text'
 import {
   type FetchState,
@@ -50,6 +51,8 @@ type Live = {
   /** This clone's `FETCH_HEAD`, watched beside the plan files; null when git names none. */
   fetchHead: string | null
   reported: Map<string, string | null>
+  /** Per lane, the ticks seen at the last read and the phase that moved last; the herd's start empties it. */
+  memories: Map<string, LaneMemory>
   pending: Timer | null
   /** The snapshot as read, without the plan chips; `snapshot` is this plus the chips of `page`. */
   read: Snapshot | null
@@ -185,7 +188,7 @@ const refresh = (live: Live, onChange: () => void): Promise<void> => {
 
 const readOnce = async (live: Live, onChange: () => void) => {
   try {
-    const read = await loadSnapshot(live.source, live.pullRequests)
+    const read = await loadSnapshot(live.source, live.pullRequests, live.memories)
     const next = withKnownPage(live, read)
     live.read = read
     if (!live.snapshot) live.view = { ...live.view, selection: startSelection(next, live.source.options) }
@@ -277,6 +280,7 @@ export const runLive = (source: Source): void => {
     watchers: new Map(),
     fetchHead: fetchHeadPath(source.root),
     reported: new Map(),
+    memories: new Map(),
     pending: null,
     read: null,
     page: null,

package/src/plans/phase-models-read.ts

@@ -0,0 +1,37 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isPhaseModelRecord, type PhaseModelRecord } from './phase-models'
+
+/** The file name the hook gives a record: 16 hex characters of a hash over plan and phase. */
+const RECORD_FILE = /^[0-9a-f]{16}\.json$/
+
+/** A record is a line of JSON; anything larger was not written by the hook. */
+const MAX_RECORD_BYTES = 4 * 1024
+
+/** A plain file of record size: a link could read elsewhere and a pipe would block the herd, so neither is read. */
+const isRecordFile = (path: string): boolean => {
+  const entry = lstatSync(path)
+  return entry.isFile() && entry.size < MAX_RECORD_BYTES
+}
+
+const recordOf = (path: string): PhaseModelRecord[] => {
+  try {
+    if (!isRecordFile(path)) return []
+    const record: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isPhaseModelRecord(record) ? [record] : []
+  } catch {
+    return []
+  }
+}
+
+/** Every record of the model log in the main checkout; nothing when the directory is missing or unreadable. */
+export const readPhaseModels = (root: string): PhaseModelRecord[] => {
+  const directory = join(root, '.jackherd', 'models')
+  try {
+    return readdirSync(directory)
+      .filter((name) => RECORD_FILE.test(name))
+      .flatMap((name) => recordOf(join(directory, name)))
+  } catch {
+    return []
+  }
+}

package/src/plans/phase-models.ts

@@ -0,0 +1,70 @@
+import { type LaneProgress, resolvePlanPath } from '../plan-format'
+import { isRecord } from '../watch/json-guards'
+
+/** The model families a phase ran on and was recommended, as lower-case words; `fits` null without a recommendation. */
+export type PhaseModel = { used: string; recommended: string | null; fits: boolean | null }
+
+/**
+ * A record as the kit's model log hook writes it to `.jackherd/models/<key>.json` in the main checkout: the plan from
+ * the repository root, the phase, the model id of the subagent's last answer and when it ended. Same shape as
+ * `PhaseModelRecord` in the hook, which this package does not import at run time.
+ */
+export type PhaseModelRecord = PhaseModel & { plan: string; phase: string; model: string; at: number }
+
+/** A family as a word of at most 16 lower-case letters, so a record cannot widen the phase row. */
+const FAMILY = /^[a-z]{1,16}$/
+
+const isFamily = (value: unknown): value is string => typeof value === 'string' && FAMILY.test(value)
+
+const isVerdict = (recommended: unknown, fits: unknown): boolean =>
+  (recommended === null && fits === null) || (isFamily(recommended) && typeof fits === 'boolean')
+
+export const isPhaseModelRecord = (value: unknown): value is PhaseModelRecord =>
+  isRecord(value) &&
+  typeof value.plan === 'string' &&
+  typeof value.phase === 'string' &&
+  typeof value.model === 'string' &&
+  isFamily(value.used) &&
+  isVerdict(value.recommended, value.fits) &&
+  typeof value.at === 'number'
+
+/** The key of a phase of a lane's step in `LaneView.models`. */
+export const phaseModelKey = (stepIndex: number, phaseId: string): string => `${stepIndex}:${phaseId}`
+
+const recordKey = (plan: string, phase: string): string => `${plan}\n${phase}`
+
+/** The newest record per plan and phase. */
+const newestByPhase = (records: readonly PhaseModelRecord[]): Map<string, PhaseModelRecord> => {
+  const newest = new Map<string, PhaseModelRecord>()
+  for (const record of records) {
+    const key = recordKey(record.plan, record.phase)
+    const known = newest.get(key)
+    if (!known || record.at > known.at) newest.set(key, record)
+  }
+  return newest
+}
+
+/** The model of every phase of the lane's steps that has a record, by `phaseModelKey`. */
+export const laneModelsOf = (
+  progress: LaneProgress,
+  records: readonly PhaseModelRecord[],
+  sprintDirectory: string,
+): Record<string, PhaseModel> => {
+  const newest = newestByPhase(records)
+  return Object.fromEntries(
+    progress.steps.flatMap(({ step, phases }, stepIndex) => {
+      const plan = step.planHref ? resolvePlanPath(sprintDirectory, step.planHref) : null
+      return phases.flatMap((phase) => {
+        const record = plan === null ? undefined : newest.get(recordKey(plan, phase.id))
+        return record
+          ? [
+              [
+                phaseModelKey(stepIndex, phase.id),
+                { used: record.used, recommended: record.recommended, fits: record.fits },
+              ],
+            ]
+          : []
+      })
+    }),
+  )
+}

package/src/plans/plan-panes.ts

@@ -1,6 +1,7 @@
 import { basename } from 'node:path'
+import { HERD_COMMAND, HERD_COMMAND_WORDS } from './herd-command'
 
-/** One herdr pane as `plans --ensure` sees it: where it is, whether an agent runs in it, its foreground commands. */
+/** One herdr pane as `herd --ensure` sees it: where it is, whether an agent runs in it, its foreground commands. */
 export type PaneState = { pane: string; tab: string; cwd: string; agent: boolean; foreground: string[][] }
 
 /** Runs a command in a free shell pane, or splits a pane to the right and runs it in the new one. */
@@ -79,7 +80,7 @@ export const foregroundOf = (json: string): string[][] => {
 
 const SHELLS = new Set(['bash', 'zsh', 'sh', 'fish', 'dash', 'ksh'])
 
-/** Arguments that make a `plans` call something other than the live view. */
+/** Arguments that make a `herd` call something other than the live view. */
 const NOT_A_VIEW = ['--once', '--ensure']
 
 const programOf = (argv: readonly string[]): string => basename(argv[0] ?? '').replace(/^-/, '')
@@ -92,12 +93,12 @@ const laneOf = (argv: readonly string[]): string | null => {
 }
 
 const isViewCall = (argv: readonly string[], lane: string | null): boolean =>
-  argv.includes('plans') &&
+  HERD_COMMAND_WORDS.includes(argv[argv.findIndex(isKitEntry) + 1] ?? '') &&
   argv.some(isKitEntry) &&
   !argv.some((arg) => NOT_A_VIEW.includes(arg)) &&
   laneOf(argv) === lane
 
-/** Whether a foreground command is the live plans view: of `lane`, or of every lane for null. */
+/** Whether a foreground command is the live herd: of `lane`, or of every lane for null. */
 export const isPlanView = (foreground: readonly (readonly string[])[], lane: string | null): boolean =>
   foreground.some((argv) => isViewCall(argv, lane))
 
@@ -125,14 +126,14 @@ export const missingCoordinatorNote = (panes: readonly PaneState[], root: string
   const inRoot = panes.filter((each) => each.agent && each.cwd === root).length
   return inRoot === 0
     ? 'coordinator: no agent in the main checkout'
-    : `coordinator: ${inRoot} agents in the main checkout and none named ${name}; run plans --ensure in its pane, or herdr agent rename <pane> ${name}`
+    : `coordinator: ${inRoot} agents in the main checkout and none named ${name}; run herd --ensure in its pane, or herdr agent rename <pane> ${name}`
 }
 
 const quoted = (arg: string): string => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`)
 
 /** The shell command that starts the view with the CLI `argv` names (runtime and entry), for `lane` or every lane. */
 export const viewCommandOf = (argv: readonly string[], lane: string | null): string =>
-  [...argv.slice(0, 2), 'plans', ...(lane ? ['--lane', lane] : [])].map(quoted).join(' ')
+  [...argv.slice(0, 2), HERD_COMMAND.name, ...(lane ? ['--lane', lane] : [])].map(quoted).join(' ')
 
 /** The new pane of a `herdr pane split` answer; throws on a changed answer. */
 export const splitPaneOf = (json: string): string => {
@@ -178,7 +179,7 @@ const inMainCheckout = (root: string, worktrees: string) => {
 const laneAnchor = (panes: readonly PaneState[], inside: (cwd: string) => boolean): PaneState | undefined =>
   panes.find((each) => inside(each.cwd) && each.agent)
 
-/** The plans views that are missing beside the coordinator and each lane, and how to bring each back. */
+/** The herd panes that are missing beside the coordinator and each lane, and how to bring each back. */
 export const planPaneActions = ({
   panes,
   coordinator,

package/src/plans/pull-requests.ts

@@ -12,10 +12,26 @@ export type PullRequest = {
   branch: string
   draft: boolean
   checks: ChecksState
+  /** The names of the checks that failed, each once, in the rollup's order; empty while none failed. */
+  failedChecks: string[]
 }
 
-/** One entry of `statusCheckRollup`: a check run carries status and conclusion, a commit status a state. */
-export type RollupEntry = { __typename?: string; status?: string; conclusion?: string | null; state?: string }
+/**
+ * One entry of `statusCheckRollup`: a check run carries a name, status, conclusion and the link to its job
+ * (`detailsUrl`), a commit status a context and a state.
+ */
+export type RollupEntry = {
+  __typename?: string
+  name?: string
+  context?: string
+  detailsUrl?: string
+  status?: string
+  conclusion?: string | null
+  state?: string
+}
+
+/** A failed check: its name, and the workflow run it belongs to when the link of its job names one. */
+export type FailedCheck = { name: string; runId: number | null }
 
 export type GhPullRequest = {
   number: number
@@ -29,6 +45,18 @@ export type GhPullRequest = {
 /** The fields `parsePullRequests` reads; pass them to `gh pr list --json`. */
 export const PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,statusCheckRollup'
 
+const RUN_IN_PATH = /^\/([\w.-]+)\/([\w.-]+)\/actions\/runs\/(\d+)(?:\/|$)/
+
+const PULL_REQUEST_PATH = /^\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)$/
+
+/** The longest check name shown or reported; a name comes from the outside. */
+export const CHECK_NAME_LENGTH = 60
+
+const DEFAULT_HOST = 'github.com'
+
+/** Where a run link must lead: `host`, and when `repository` (`<owner>/<repo>`) is set, that repository only. */
+export type RunScope = { host: string; repository: string | null }
+
 const FAILED = new Set(['FAILURE', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'ERROR'])
 const PENDING_STATES = new Set(['PENDING', 'EXPECTED'])
 
@@ -44,7 +72,52 @@ export const checksOf = (rollup: readonly RollupEntry[]): ChecksState => {
   return rollup.some(isPending) ? CHECKS.pending : CHECKS.passed
 }
 
-const PULL_REQUEST_PATH = /^\/[\w.-]+\/[\w.-]+\/pull\/(\d+)$/
+/**
+ * The workflow run a link of a check names: `https://<host>/<owner>/<repo>/actions/runs/<id>` with an optional rest.
+ * The link comes from the outside and ends up as an argument of `gh run view`, so the host must be `scope.host`
+ * (without credentials, over https), the repository `scope.repository` when set, and the id a safe integer.
+ */
+export const runIdOfLink = (
+  link: string | undefined,
+  scope: RunScope = { host: DEFAULT_HOST, repository: null },
+): number | null => {
+  try {
+    const url = new URL(link ?? '')
+    const match = url.pathname.match(RUN_IN_PATH)
+    const own = url.protocol === 'https:' && url.hostname === scope.host && url.username === '' && url.password === ''
+    const sameRepository = scope.repository === null || `${match?.[1]}/${match?.[2]}` === scope.repository
+    const id = Number(match?.[3])
+    return own && match && sameRepository && Number.isSafeInteger(id) ? id : null
+  } catch {
+    return null
+  }
+}
+
+/** The scope of a pull request page: its host and repository, null when the page is not one. */
+const scopeOfPullRequest = (pullRequestUrl: string | undefined): RunScope | undefined => {
+  if (pullRequestUrl === undefined) return undefined
+  try {
+    const url = new URL(pullRequestUrl)
+    const path = url.pathname.match(PULL_REQUEST_PATH)
+    return { host: url.hostname, repository: path ? `${path[1]}/${path[2]}` : null }
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The checks of the rollup that failed, each name once with the run of its first failure, in the rollup's order. Names
+ * come from the outside and are made terminal-safe; an entry without a name is left out.
+ */
+export const failedChecksOf = (rollup: readonly RollupEntry[], pullRequestUrl?: string): FailedCheck[] => {
+  const scope = scopeOfPullRequest(pullRequestUrl)
+  const failed = new Map<string, FailedCheck>()
+  for (const entry of rollup.filter(isFailed)) {
+    const name = terminalSafe(entry.name ?? entry.context ?? '').trim()
+    if (name !== '' && !failed.has(name)) failed.set(name, { name, runId: runIdOfLink(entry.detailsUrl, scope) })
+  }
+  return [...failed.values()]
+}
 
 /** True only for `https://<host>/<owner>/<repo>/pull/<number>` of this very pull request: the view opens it on a click. */
 const isPullRequestPage = (url: string, number: number, host: string): boolean => {
@@ -52,7 +125,7 @@ const isPullRequestPage = (url: string, number: number, host: string): boolean =
     const parsed = new URL(url)
     const path = parsed.pathname.match(PULL_REQUEST_PATH)
     const exact = parsed.href === url && parsed.search === '' && parsed.hash === ''
-    return exact && parsed.protocol === 'https:' && parsed.hostname === host && Number(path?.[1]) === number
+    return exact && parsed.protocol === 'https:' && parsed.hostname === host && Number(path?.[3]) === number
   } catch {
     return false
   }
@@ -89,6 +162,7 @@ export const parsePullRequests = (json: string, host = 'github.com'): PullReques
     branch: terminalSafe(pullRequest.headRefName),
     draft: pullRequest.isDraft,
     checks: checksOf(pullRequest.statusCheckRollup ?? []),
+    failedChecks: failedChecksOf(pullRequest.statusCheckRollup ?? [], pullRequest.url).map(({ name }) => name),
   }))
 }
 

package/src/plans/selection.ts

@@ -12,7 +12,7 @@ export type LaneFold = { status: string | null; open: boolean }
 /**
  * The row under the cursor and the expanded phases, both as keys, whether ticked phases and items are
  * listed one by one or summed up in one line, whether the footer shows the symbol legend, and the
- * folds of the lanes by lane name, and the lanes whose notes (sprint rows without a phase) are listed.
+ * folds of the lanes by lane name.
  */
 export type Selection = {
   selected: string | null
@@ -20,7 +20,6 @@ export type Selection = {
   showDone: boolean
   showLegend: boolean
   laneFolds: ReadonlyMap<string, LaneFold>
-  notesShown: ReadonlySet<string>
 }
 
 /** A lane as the folds need it: its name and the status its agent reports, null without an agent. */
@@ -51,7 +50,6 @@ export const INPUT = {
   collapse: ['\x1b[D', '\x1bOD', 'h'],
   showDone: ['a'],
   legend: ['?'],
-  notes: ['n'],
   sprintPage: ['s'],
   pageUp: ['\x1b[5~'],
   pageDown: ['\x1b[6~'],
@@ -73,13 +71,9 @@ export const PLANNED_KEY = 'planned'
 
 export const phaseKey = (lane: string, stepIndex: number, phaseId: string): string => `${lane}:${stepIndex}:${phaseId}`
 
-const NOTES_KEY_PREFIX = 'notes>'
 const FOLLOWING_KEY_PREFIX = 'following>'
 const TICKED_KEY_PREFIX = 'ticked>'
 
-/** The key of the row that shows or hides the notes of a lane; selectable, since a key reaches it too. */
-export const notesKey = (lane: string): string => `${NOTES_KEY_PREFIX}${lane}`
-
 /** The key of the folded row under a lane that lists the open phases after its own. */
 export const followingKey = (lane: string): string => `${FOLLOWING_KEY_PREFIX}${lane}`
 
@@ -98,12 +92,6 @@ export const itemKey = (phase: string, index: number): string => `${phase}#${ind
 /** The phase a task key belongs to, null for any other key. */
 export const itemPhaseOfKey = (key: string): string | null => key.match(ITEM_KEY)?.[1] ?? null
 
-const notesLaneOfKey = (key: string): string | null =>
-  key.startsWith(NOTES_KEY_PREFIX) ? key.slice(NOTES_KEY_PREFIX.length) : null
-
-const followingLaneOfKey = (key: string): string | null =>
-  key.startsWith(FOLLOWING_KEY_PREFIX) ? key.slice(FOLLOWING_KEY_PREFIX.length) : null
-
 const tickedPhaseOfKey = (key: string): string | null =>
   key.startsWith(TICKED_KEY_PREFIX) ? key.slice(TICKED_KEY_PREFIX.length) : null
 
@@ -114,12 +102,6 @@ export const laneKey = (lane: string): string => `${LANE_KEY_PREFIX}${lane}`
 
 const laneOfKey = (key: string): string | null => (key.startsWith(LANE_KEY_PREFIX) ? key.slice(1) : null)
 
-const PHASE_KEY = /^(.+):\d+:[^:]+$/
-
-/** The lane a row belongs to: its own row or one of its phases; null for a pull request row. */
-const laneNameOfKey = (key: string): string | null =>
-  laneOfKey(key) ?? notesLaneOfKey(key) ?? followingLaneOfKey(key) ?? key.match(PHASE_KEY)?.[1] ?? null
-
 /** Working and blocked lanes show their phases; idle and done ones, and lanes without an agent, fold into one line. */
 export const autoOpen = (status: string | null): boolean =>
   status !== null && status !== AGENT_STATUS.idle && status !== AGENT_STATUS.done
@@ -153,7 +135,6 @@ export const overviewSelection = (): Selection => ({
   showDone: false,
   showLegend: false,
   laneFolds: new Map(),
-  notesShown: new Set(),
 })
 
 /** The lane view opens its lane and, when it has a current phase, that phase, expanded. */
@@ -200,13 +181,6 @@ const foldLane = (selection: Selection, lane: string, next: (open: boolean) => b
   return { ...selection, laneFolds: new Map(selection.laneFolds).set(lane, { ...fold, open: next(fold.open) }) }
 }
 
-const withNotes = (selection: Selection, lane: string, next: (shown: boolean) => boolean): Selection => {
-  const notesShown = new Set(selection.notesShown)
-  if (next(notesShown.has(lane))) notesShown.add(lane)
-  else notesShown.delete(lane)
-  return { ...selection, notesShown }
-}
-
 /** Opens a task and the phase it belongs to. */
 const openTaskWithPhase = (expanded: Set<string>, phase: string, task: string): void => {
   expanded.add(phase)
@@ -215,8 +189,6 @@ const openTaskWithPhase = (expanded: Set<string>, phase: string, task: string):
 
 /** Selects a row and opens it, or closes it when it is already open: a phase shows its items, a lane its phases. */
 export const applyClick = (selection: Selection, key: string): Selection => {
-  const notesLane = notesLaneOfKey(key)
-  if (notesLane !== null) return { ...withNotes(selection, notesLane, flipped), selected: key }
   const phase = tickedPhaseOfKey(key)
   if (phase !== null) return { ...selection, showDone: !selection.showDone, selected: phase }
   const lane = laneOfKey(key)
@@ -236,8 +208,6 @@ const toggle = (selection: Selection, keys: readonly string[]): Selection => {
 const changeSelected = (selection: Selection, keys: readonly string[], next: (open: boolean) => boolean): Selection => {
   const current = selectedKey(selection, keys)
   if (!current) return selection
-  const notesLane = notesLaneOfKey(current)
-  if (notesLane !== null) return { ...withNotes(selection, notesLane, next), selected: current }
   const lane = laneOfKey(current)
   if (lane !== null) return { ...foldLane(selection, lane, next), selected: current }
   const expanded = new Set(selection.expanded)
@@ -253,14 +223,6 @@ const expand = (selection: Selection, keys: readonly string[]): Selection => cha
 
 const collapse = (selection: Selection, keys: readonly string[]): Selection => changeSelected(selection, keys, closed)
 
-/** Lists or hides the notes of the lane under the cursor. */
-const toggleNotes = (selection: Selection, keys: readonly string[]): Selection => {
-  const current = selectedKey(selection, keys)
-  const lane = current ? laneNameOfKey(current) : null
-  if (!lane) return selection
-  return withNotes(selection, lane, flipped)
-}
-
 export const applyKey = (selection: Selection, input: string, keys: readonly string[]): Selection => {
   if (isInput(INPUT.up, input)) return move(selection, keys, -1)
   if (isInput(INPUT.down, input)) return move(selection, keys, 1)
@@ -268,7 +230,6 @@ export const applyKey = (selection: Selection, input: string, keys: readonly str
   if (isInput(INPUT.expand, input)) return expand(selection, keys)
   if (isInput(INPUT.collapse, input)) return collapse(selection, keys)
   if (isInput(INPUT.showDone, input)) return { ...selection, showDone: !selection.showDone }
-  if (isInput(INPUT.notes, input)) return toggleNotes(selection, keys)
   if (isInput(INPUT.legend, input)) return { ...selection, showLegend: !selection.showLegend }
   return selection
 }

package/src/plans/settings.ts

@@ -4,6 +4,7 @@ import { type JackherdConfig, parseJackherdConfig } from '../config'
 import { PROJECT_CONFIG_PATH } from '../config/location'
 import { readConfig } from '../config/read-config'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import type { TicketSource } from '../watch/plan-badges'
 
 export const CONFIG_PATH = PROJECT_CONFIG_PATH
 
@@ -15,6 +16,8 @@ export type PlansSettings = Pick<
   fetchIntervalMinutes: number
   linkKinds: JackherdConfig['plans']['linkKinds']
   context: JackherdConfig['plans']['context']
+  /** The `watch.sources` marked `ticket`, whose entries the view shows as badges. */
+  ticketSources: TicketSource[]
 }
 
 const CLOCK_LOCALE: Record<PlanLanguage, string> = {
@@ -22,7 +25,7 @@ const CLOCK_LOCALE: Record<PlanLanguage, string> = {
   [PLAN_LANGUAGE.en]: 'en-GB',
 }
 
-/** The plans view's slice of a validated config. */
+/** The herd's slice of a validated config. */
 export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   planDirectory: config.planDirectory,
   board: config.board,
@@ -34,9 +37,12 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
   linkKinds: config.plans.linkKinds,
   context: config.plans.context,
+  ticketSources: config.watch.sources.flatMap(({ name, lane, ticket }) =>
+    ticket ? [{ name, lane: lane ?? null }] : [],
+  ),
 })
 
-/** The plans view's slice of `.jackherd/config.json`, validated by the shared schema. */
+/** The herd's slice of `.jackherd/config.json`, validated by the shared schema. */
 export const parsePlansSettings = (raw: unknown): PlansSettings => plansSettingsOf(parseJackherdConfig(raw ?? {}))
 
 /** Board documents, relative to the main checkout. */
@@ -63,6 +69,6 @@ export const baseRefOf = ({ baseBranch }: Pick<PlansSettings, 'baseBranch'>): st
 
 export const clockLocaleOf = (settings: PlansSettings): string => CLOCK_LOCALE[settings.responseLanguage]
 
-/** The plans view's settings from the config `readConfig` finds. */
+/** The herd's settings from the config `readConfig` finds. */
 export const readSettings = (roots: string[], home: string = homedir()): PlansSettings =>
   plansSettingsOf(readConfig(roots, home))

package/src/plans/shown-with-more.ts

@@ -0,0 +1,5 @@
+/** The first `limit` of `items`, and how many are left out; never negative. */
+export const shownWithMore = <T>(items: readonly T[], limit: number): { shown: T[]; more: number } => ({
+  shown: items.slice(0, limit),
+  more: Math.max(items.length - limit, 0),
+})