@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/run/board/run-board-render-foot.ts

@@ -0,0 +1,59 @@
+import type { BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import { run_board_layout } from './run-board-layout'
+import type { Link } from './run-board-link'
+import type { BoardNote } from './run-board-notes'
+import { run_board_render_drawn } from './run-board-render-drawn'
+import { run_board_render_icon } from './run-board-render-icon'
+import { run_board_render_legend } from './run-board-render-legend'
+import { run_board_render_thanks } from './run-board-render-thanks'
+import { run_board_render_waits } from './run-board-render-waits'
+import type { Thanks } from './run-board-thanks-csv'
+
+// The lines around a frame's rows that no row draws — pure: the command a stopped run resumes from
+// under the header, and the reviewers thanked, the stray waits and the legend at the foot.
+
+const { STATE_ICONS, WORDS } = run_board_labels
+const GAP = '  '
+
+// The command that resumes a stopped run's session, under the header where the person looks first.
+function resume_lines(resume: string | undefined): Array<string> {
+	if (resume === undefined) return []
+
+	return ['', `${STATE_ICONS.human} ${WORDS.resume}${GAP}claude --resume ${resume}`]
+}
+
+// No legend is drawn before a plan is read, nor where the frame draws nothing it would name.
+function legend_of(header: BoardHeader, notes: ReadonlyArray<BoardNote>): Array<string> {
+	const { layout } = header
+
+	if (layout === undefined) return []
+
+	const rows = run_board_layout.drawn_rows(layout)
+	const leads = new Set(rows.map((row) => run_board_render_icon.state_icon(row)))
+	const drawn = run_board_render_drawn.drawn_of(header, rows, leads)
+
+	return run_board_render_legend.legend_of(rows, drawn, notes)
+}
+
+// The waits no lane row owns, right before the legend (joshuafolkken/kit#4052), and the legend.
+function legend_lines(header: BoardHeader, notes: ReadonlyArray<BoardNote>): Array<string> {
+	const lines = [...run_board_render_waits.stray_lines(header), ...legend_of(header, notes)]
+
+	return lines.length === 0 ? [] : ['', ...lines]
+}
+
+// Names with no link where no terminal opens one: a frame with no `link` draws them plain.
+function thanks_part(
+	thanks: Thanks | undefined,
+	link: Link | undefined,
+	columns: number | undefined,
+): Array<string> {
+	const linked = link ?? ((text: string): string => text)
+
+	return run_board_render_thanks.thanks_lines(thanks ?? [], linked, columns)
+}
+
+const run_board_render_foot = { legend_lines, resume_lines, thanks_part }
+
+export { run_board_render_foot }

package/scripts/run/board/run-board-render-icon.ts

@@ -0,0 +1,35 @@
+import { run_board_earlier } from './run-board-earlier'
+import { run_board_labels } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+
+// The icon a `run:board` row leads with: its state's, or its phase's while it runs. A held lane keeps
+// it, 🚧 standing in the progress column before it (joshuafolkken/kit#4292).
+
+const { PHASE_ICONS, STATE_ICONS } = run_board_labels
+const { EARLIER_ICON } = run_board_earlier
+
+// A row that says what it waits on leads with that wait's icon in place of its state's
+// (joshuafolkken/kit#4288).
+function state_lead(row: BoardRow): string {
+	return row.reason?.icon ?? STATE_ICONS[row.state]
+}
+
+// A running row leads with the icon of the phase it is in now — the last its track reached — and
+// with 🔄 while it has reached none yet; an earlier run's running lane leads with 🧳 in its place.
+function running_lead(row: BoardRow): string {
+	const current = row.status?.track?.at(-1)
+
+	return current === undefined ? state_lead(row) : PHASE_ICONS[current]
+}
+
+function state_icon(row: BoardRow): string {
+	if (row.state !== 'running') return state_lead(row)
+
+	return row.is_earlier === true ? EARLIER_ICON : running_lead(row)
+}
+
+const run_board_render_icon = {
+	state_icon,
+}
+
+export { run_board_render_icon }

package/scripts/run/board/run-board-render-lanes.ts

@@ -0,0 +1,145 @@
+import { run_board_earlier } from './run-board-earlier'
+import { run_board_fit, type PlanLine, type PlanSection } from './run-board-fit'
+import type { BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+import { run_board_render_lead } from './run-board-render-lead'
+import { run_board_render_section, type RuleColumn } from './run-board-render-section'
+import type { LaneUsages, UsageFigure, UsageScale } from './run-board-usage'
+import { run_board_usage_text, type CellLimits } from './run-board-usage-text'
+
+// The run's own rows' CPU, MEM and CMPRS cells, right after each row's lead and before its number,
+// under a rule whose labels stand over them and over the run's time: `── 🧵 lanes ── ⏰ ── 💪 CPU ─
+// 🧠 MEM ─ 🤏 CMPRS ───`. The cells start at `USAGE_START`, as the processes rows' do, so the two
+// sections' figures stand in one column (joshuafolkken/kit#4292). A running row draws its lane's
+// figures; every other row blanks of the same width, so every number and title after them starts in
+// one column. Drawn with gauges on a terminal and as figures alone anywhere else.
+
+const { HEADER_ICONS } = run_board_labels
+const { cell_widths, cells_of, lane_limits } = run_board_usage_text
+const { columns_rule } = run_board_render_section
+const { ELAPSED_START, USAGE_START } = run_board_render_lead
+const { width_of } = run_board_fit
+const GAUGE = 5
+const CELL_GAP = ' '
+// What a column needs past its label so the next label still has a rule before it: ` ─`.
+const LABEL_TAIL = 2
+// Icons Unicode draws as emoji by default, which `string-width` counts two columns wide as a
+// terminal draws them: 🛤 and 🗜, text symbols drawn as emoji, overlapped the blank after them.
+const LANES_LABEL = `${run_board_labels.LANES_ICON} lanes`
+const COLUMN_LABELS = [`${HEADER_ICONS.cpu} CPU`, `${HEADER_ICONS.memory} MEM`, '🤏 CMPRS']
+
+// What one frame's lane cells are drawn with.
+interface LaneCells {
+	usages: LaneUsages
+	scale: UsageScale
+	// Where each live row's gauges are full — its share of the header's yellow thresholds, counted once a
+	// frame.
+	limits: CellLimits
+	gauge: number
+	// The widest row number of the section, so the kind icon and title after it start in one column.
+	number_width: number
+}
+
+// The gauge drawn after each figure — none where the frame is not drawn on a terminal, which draws no
+// spinner.
+function gauge_of(header: BoardHeader): number {
+	return header.spinner === undefined ? 0 : GAUGE
+}
+
+// Each column's width: its cell's, widened where its label is wider.
+function column_widths(gauge: number): Array<number> {
+	return cell_widths(gauge).map((width, index) =>
+		Math.max(width, width_of(COLUMN_LABELS[index] ?? '') + LABEL_TAIL),
+	)
+}
+
+// A figure's cells, each right-aligned in its column — full at `limits` where a lane row passes its
+// share, at the whole machine where not.
+function column_cells(
+	figure: UsageFigure | undefined,
+	scale: UsageScale,
+	gauge: number,
+	limits?: CellLimits,
+): string {
+	const widths = column_widths(gauge)
+	const cells = cells_of(figure, scale, gauge, limits).map(
+		(cell, index) => `${' '.repeat(Math.max(0, (widths[index] ?? 0) - width_of(cell)))}${cell}`,
+	)
+
+	return cells.join(CELL_GAP)
+}
+
+// `undefined` where the frame read no usage, which draws no cells.
+function lane_cells_of(header: BoardHeader, rows: ReadonlyArray<BoardRow>): LaneCells | undefined {
+	const { usages } = header
+
+	if (usages === undefined) return undefined
+
+	const running = rows.filter((row) => run_board_earlier.is_live(row)).length
+
+	return {
+		usages: usages.lanes,
+		scale: usages.scale,
+		limits: lane_limits(running),
+		gauge: gauge_of(header),
+		number_width: Math.max(0, ...rows.map((row) => String(row.number).length)),
+	}
+}
+
+// A row's number as linked — where cells are drawn, after them and padded to the section's widest.
+function number_text(
+	row: BoardRow,
+	cells: LaneCells | undefined,
+	link: (text: string) => string,
+): string {
+	const number = String(row.number)
+
+	if (cells === undefined) return link(number)
+
+	const figure = run_board_earlier.is_live(row) ? cells.usages.get(row.number) : undefined
+	const drawn = column_cells(figure, cells.scale, cells.gauge, cells.limits)
+
+	return `${drawn} ${link(number)}${' '.repeat(cells.number_width - number.length)}`
+}
+
+// Each column's label, placed at the column its cells start at, the first at `first`.
+function label_columns(first: number, gauge: number): Array<RuleColumn> {
+	let start = first
+
+	return column_widths(gauge).map((width, index) => {
+		const column = { label: COLUMN_LABELS[index] ?? '', start }
+
+		start += width + CELL_GAP.length
+
+		return column
+	})
+}
+
+// The run's own rows under the lanes rule, ⏰ over the run's time and the usage labels over their
+// cells where they are drawn.
+function lanes_section(
+	lines: ReadonlyArray<PlanLine>,
+	cells: LaneCells | undefined,
+): Array<PlanSection> {
+	if (lines.length === 0) return []
+
+	const elapsed = { label: HEADER_ICONS.elapsed, start: ELAPSED_START }
+	const usage = cells === undefined ? [] : label_columns(USAGE_START, cells.gauge)
+	const rule = columns_rule(LANES_LABEL, [elapsed, ...usage])
+
+	return [{ head: ['', rule], lines, label: LANES_LABEL, key: 'lanes' }]
+}
+
+const run_board_render_lanes = {
+	COLUMN_LABELS,
+	LANES_LABEL,
+	column_cells,
+	label_columns,
+	lane_cells_of,
+	lanes_section,
+	number_text,
+}
+
+export { run_board_render_lanes }
+export type { LaneCells }

package/scripts/run/board/run-board-render-lead.ts

@@ -0,0 +1,80 @@
+import { run_board_earlier } from './run-board-earlier'
+import { run_board_fresh } from './run-board-fresh'
+import type { BoardHeader } from './run-board-header'
+import type { BoardRow } from './run-board-layout'
+import { run_board_render_icon } from './run-board-render-icon'
+import { run_board_render_tail } from './run-board-render-tail'
+import { run_board_render_time } from './run-board-render-time'
+import { run_board_render_waits } from './run-board-render-waits'
+
+// What a lane row draws before its usage cells (joshuafolkken/kit#4292): the progress column — the
+// spinner while it runs, 🚧 while its lane is held, blanks where it stopped — the phase's icon, how
+// long it has stood at the phase and how long it has run, each time eight columns right-aligned. A held
+// lane draws why and how long it is held in the run's time's place, so every column after it stays put.
+
+const { BUDGET_ICON, held_of, held_time } = run_board_render_waits
+const { phase_time } = run_board_render_tail
+const { state_icon } = run_board_render_icon
+const { time_of } = run_board_render_time
+// The widest span a time column draws: `1°14′58″`.
+const TIME_WIDTH = 8
+const LANE_INDENT = '  '
+// The progress column: an emoji two columns wide, or the spinner and a blank.
+const PROGRESS_WIDTH = 2
+const PROGRESS_BLANK = ' '.repeat(PROGRESS_WIDTH)
+const ICON_WIDTH = 2
+const SPACE = 1
+// The column the run's time starts at, which the rule's ⏰ stands over.
+const ELAPSED_START =
+	LANE_INDENT.length + PROGRESS_WIDTH + SPACE + ICON_WIDTH + SPACE + TIME_WIDTH + SPACE
+// The column a lane row's usage cells start at, after the lead and one blank; the processes rows' too.
+const USAGE_START = ELAPSED_START + TIME_WIDTH + SPACE
+
+// A running row's part that changed at `at_ms`, emphasized while fresh (`run-board-fresh.ts`) — its
+// start and its phase; a settled row's are long past.
+function running_fresh(
+	row: BoardRow,
+	text: string,
+	at_ms: number | undefined,
+	header: BoardHeader,
+): string {
+	return run_board_earlier.is_live(row) ? run_board_fresh.since(text, at_ms, header) : text
+}
+
+function progress_of(row: BoardRow, header: BoardHeader): string {
+	if (held_of(row, header) !== undefined) return BUDGET_ICON
+	if (row.state !== 'running' || header.spinner === undefined) return PROGRESS_BLANK
+
+	return `${header.spinner} `
+}
+
+// How long the row has run, or why and how long its lane is held while it is.
+function whole_of(row: BoardRow, header: BoardHeader): string {
+	const held = held_of(row, header)
+
+	if (held !== undefined) return held_time(held, TIME_WIDTH)
+
+	const time = time_of(row, header.now_ms) ?? ''
+	const fresh = running_fresh(row, time, row.status?.started_ms, header)
+
+	return run_board_fresh.padded(time, TIME_WIDTH, fresh)
+}
+
+// A lane row's lead after its indent, ending where its usage cells start less one blank.
+function lead_of(row: BoardRow, header: BoardHeader): string {
+	const icon = running_fresh(row, state_icon(row), row.status?.phase_ms, header)
+	const phase = phase_time(row, header, TIME_WIDTH)
+
+	return [progress_of(row, header), icon, phase, whole_of(row, header)].join(' ')
+}
+
+const run_board_render_lead = {
+	ELAPSED_START,
+	LANE_INDENT,
+	TIME_WIDTH,
+	USAGE_START,
+	lead_of,
+	running_fresh,
+}
+
+export { run_board_render_lead }

package/scripts/run/board/run-board-render-legend.ts

@@ -1,49 +1,80 @@
 import { styleText } from 'node:util'
 import type { FiledKind } from '#scripts/run/event/run-event-filed'
+import { run_board_earlier } from './run-board-earlier'
 import { run_board_kind } from './run-board-kind'
 import { run_board_labels, type Words } from './run-board-labels'
 import type { BoardRow } from './run-board-layout'
-import type { BoardNote } from './run-board-notes'
+import { run_board_notes, type BoardNote } from './run-board-notes'
 import { run_board_phase } from './run-board-phase'
 import { run_board_render_notes } from './run-board-render-notes'
 import type { ItemState } from './run-board-status'
 
-// The legend at the foot of `run:board`: the symbols named once, so a row carries only what differs
-// between rows. Drawn apart from the rows, which tell it the icons they lead with.
+// The legend at the foot of `run:board`: the symbols the frame draws, named once, so a row carries
+// only what differs between rows. Drawn apart from the rows, which tell it the icons they draw.
+// joshuafolkken/kit#4047: each naming only what the frame draws, on one line. An icon the frame draws
+// beside its own word is not named — ⏳ under `⏳ queued`, 🙋 under `🙋 decision`, ✅ under `✅ done`
+// and 📌 on `📌 findings` — so the legend names only an icon drawn with no word beside it, what a
+// waiting row leads with among them.
 
-const { FILED_KIND_ICONS, KIND_WORDS, PHASE_ICONS, PHASE_WORDS, STATE_ICONS, WAITS_ICON, WORDS } =
-	run_board_labels
+const {
+	FILED_KIND_ICONS,
+	FILED_RUN_MARK,
+	KIND_WORDS,
+	PHASE_ICONS,
+	PHASE_WORDS,
+	STATE_ICONS,
+	WAITS_ICON,
+	WAIT_WORDS,
+	WORDS,
+} = run_board_labels
 const GAP = '  '
 
-// Every phase a run passes through, in the order a run passes them and whatever is on screen: a row's phase
-// moves between redraws, so fixed lines keep each icon where the eye last found it — six to a line, so
-// the twelve fit a narrow pane.
-const PHASES_PER_LINE = 6
-const PHASE_ENTRIES = run_board_phase.PHASES.map(
-	(phase) => `${PHASE_ICONS[phase]} ${WORDS[PHASE_WORDS[phase]]}`,
-)
-const PHASE_LEGEND = Array.from(
-	{ length: Math.ceil(PHASE_ENTRIES.length / PHASES_PER_LINE) },
-	(_, line) => PHASE_ENTRIES.slice(line * PHASES_PER_LINE, (line + 1) * PHASES_PER_LINE).join(GAP),
-)
-
-// The row states the legend can name, in its order, each with its word.
-const STATE_LEGEND: ReadonlyArray<readonly [ItemState, keyof Words]> = [
-	['merged', 'merged'],
-	['parked', 'parked'],
-	['done', 'done'],
-	['withdrawn', 'withdrawn'],
-	['running', 'in_progress'],
-	['stopped', 'stopped'],
-	['waiting', 'waiting'],
-	['human', 'decision'],
+// What the frame draws, as the legend reads it.
+interface LegendDrawn {
+	// The icons the rows lead with — a running row leads with its phase, so 🔄 is named only while a
+	// row draws it.
+	leads: ReadonlySet<string>
+	// Every icon a phase may be drawn with: the rows' leads, the header's third line and the rows' ends.
+	icons: ReadonlySet<string>
+	// The activity kinds the header's third line and the rows' ends draw, where their own words do not
+	// name them (joshuafolkken/kit#3767, joshuafolkken/kit#3769).
+	named: ReadonlyArray<string>
+	// What a followup row's checks draw (joshuafolkken/kit#3770).
+	checks: ReadonlyArray<string>
+	// 🚧 and the reasons a held check is drawn with (joshuafolkken/kit#4052).
+	held: ReadonlyArray<string>
+}
+
+type LeadWords = ReadonlyArray<readonly [string, keyof Words]>
+
+function states_of(states: ReadonlyArray<readonly [ItemState, keyof Words]>): LeadWords {
+	return states.map(([state, word]) => [STATE_ICONS[state], word] as const)
+}
+
+// The row leads the legend can name, each with its word: in progress first, then the settled ones.
+const PROGRESS_STATES: LeadWords = states_of([['running', 'in_progress']])
+const SETTLED_STATES: LeadWords = [
+	...states_of([
+		['parked', 'parked'],
+		['paused', 'paused'],
+		['stopped', 'stopped'],
+	]),
+	[run_board_earlier.EARLIER_ICON, 'earlier'],
+	...states_of([
+		['unknown', 'unknown'],
+		['done', 'done'],
+		['withdrawn', 'withdrawn'],
+	]),
 ]
 
-// The states some row on screen leads with (`drawn`) — a running row leads with its phase, so 🔄 is
-// named only while a row draws it.
-function state_legend(drawn: ReadonlySet<string>): Array<string> {
-	return STATE_LEGEND.filter(([state]) => drawn.has(STATE_ICONS[state])).map(
-		([state, word]) => `${STATE_ICONS[state]} ${WORDS[word]}`,
+function state_legend(states: LeadWords, leads: ReadonlySet<string>): Array<string> {
+	return states.filter(([icon]) => leads.has(icon)).map(([icon, word]) => `${icon} ${WORDS[word]}`)
+}
+
+// The phases the frame draws, in the order a run passes them.
+function phase_legend(icons: ReadonlySet<string>): Array<string> {
+	return run_board_phase.PHASES.filter((phase) => icons.has(PHASE_ICONS[phase])).map(
+		(phase) => `${PHASE_ICONS[phase]} ${WORDS[PHASE_WORDS[phase]]}`,
 	)
 }
 
@@ -54,35 +85,72 @@ function kinds_of(rows: ReadonlyArray<BoardRow>): Array<FiledKind> {
 	return run_board_kind.KIND_ORDER.filter((kind) => drawn.has(kind))
 }
 
+// The wait icon a row draws: the one a waiting row leads with, which names its blockers itself, else
+// 🔗 where blockers follow the title of a row that waits on no condition of its own.
+function wait_icon(row: BoardRow): string | undefined {
+	return row.reason?.icon ?? (row.waits.length > 0 ? WAITS_ICON : undefined)
+}
+
+// What the waiting rows the frame draws lead with (joshuafolkken/kit#4288), in one fixed order.
 function waits_legend(rows: ReadonlyArray<BoardRow>): Array<string> {
-	return rows.some((row) => row.waits.length > 0) ? [`${WAITS_ICON} ${WORDS.waits}`] : []
+	const drawn = new Set(rows.map((row) => wait_icon(row)))
+
+	return WAIT_WORDS.filter(([icon]) => drawn.has(icon)).map(
+		([icon, word]) => `${icon} ${WORDS[word]}`,
+	)
 }
 
-// The phases on their lines and what the screen draws on one more, drawn only when it names something.
-// The header's gauges and marks read by their place, so the legend leaves them.
-// `drawn` is the icons the rows lead with; `named` the activity kinds the header's third line and the
-// rows' tails draw, each named once, where their own words do not name them (joshuafolkken/kit#3767,
-// joshuafolkken/kit#3769).
-function legend_of(
+// ✚ is named only while a row the run filed draws it (joshuafolkken/kit#4099).
+function filed_legend(
+	rows: ReadonlyArray<BoardRow>,
+	notes: ReadonlyArray<BoardNote>,
+): Array<string> {
+	const filed = run_board_notes.filed_numbers(notes)
+
+	return rows.some((row) => filed.has(row.number)) ? [`${FILED_RUN_MARK} ${WORDS.filed_run}`] : []
+}
+
+// What is in progress, then what has settled.
+function states_line(drawn: LegendDrawn): Array<string> {
+	return [
+		...state_legend(PROGRESS_STATES, drawn.leads),
+		...phase_legend(drawn.icons),
+		...new Set(drawn.named),
+		...state_legend(SETTLED_STATES, drawn.leads),
+	]
+}
+
+// The kinds, then the rest. The header's gauges and marks read by their place, so the legend leaves
+// them.
+function others_line(
 	rows: ReadonlyArray<BoardRow>,
-	drawn: ReadonlySet<string>,
+	drawn: LegendDrawn,
 	notes: ReadonlyArray<BoardNote>,
-	named: ReadonlyArray<string> = [],
 ): Array<string> {
 	const kinds = kinds_of(rows)
 	const kind_icons = kinds.map((kind) => FILED_KIND_ICONS[kind])
-	const notes_named = run_board_render_notes.notes_legend(notes, new Set([...drawn, ...kind_icons]))
+	const named = new Set([...drawn.leads, ...kind_icons])
 	const kind_named = kinds.map((kind) => `${FILED_KIND_ICONS[kind]} ${WORDS[KIND_WORDS[kind]]}`)
-	const shown = [
-		...new Set(named),
-		...state_legend(drawn),
+
+	return [
 		...kind_named,
 		...waits_legend(rows),
-		...notes_named,
+		...filed_legend(rows, notes),
+		...drawn.held,
+		...drawn.checks,
+		...run_board_render_notes.notes_legend(notes, named, rows),
 	]
-	const lines = shown.length === 0 ? PHASE_LEGEND : [...PHASE_LEGEND, shown.join(GAP)]
+}
+
+// One line, drawn only when it names something.
+function legend_of(
+	rows: ReadonlyArray<BoardRow>,
+	drawn: LegendDrawn,
+	notes: ReadonlyArray<BoardNote>,
+): Array<string> {
+	const entries = [...states_line(drawn), ...others_line(rows, drawn, notes)]
 
-	return lines.map((line) => styleText('dim', line))
+	return entries.length === 0 ? [] : [styleText('dim', entries.join(GAP))]
 }
 
 const run_board_render_legend = {
@@ -90,3 +158,4 @@ const run_board_render_legend = {
 }
 
 export { run_board_render_legend }
+export type { LegendDrawn }