@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/run/add/run-add.ts

@@ -0,0 +1,124 @@
+import { AUTO_OK_LABEL, PRIORITY_HIGH_LABEL, RUN_LANE_LABEL } from '#scripts/issue/issue-labels'
+import type { CarryAddition } from '#scripts/run/carry/run-carry-added'
+
+// `josh run:add` — put an issue into a live `backlogrun`. A pool run picks an issue up only once it
+// carries `auto-ok` and `run:lane`, and takes a `priority:high` one first; a `--only` run reads its
+// named list off the carry record. **A running child is never interrupted**: an added issue takes the
+// next lane that frees, ahead of the rest unless `--no-priority` puts it at the end.
+//
+// What is decided here is per issue and pure over its ports, so a suite drives every outcome without
+// `gh`; `run-add-cli.ts` finds the run, wires the ports and writes the record.
+
+interface IssueView {
+	is_open: boolean
+	// The open issues this one is blocked by. A blocked issue is accepted and said to be waiting: the
+	// run reaches it once its blockers close, as a named issue's blockers are honored.
+	blockers: ReadonlyArray<number>
+}
+
+interface AddPorts {
+	read_issue: (issue: number) => Promise<IssueView | undefined>
+	apply_label: (issue: number, label: string) => Promise<boolean>
+}
+
+type AddOutcome =
+	| { kind: 'queued'; issue: number; blockers: ReadonlyArray<number> }
+	| { kind: 'closed'; issue: number }
+	| { kind: 'unreadable'; issue: number }
+	| { kind: 'unlabeled'; issue: number; label: string }
+
+const ISSUE_PREFIX = '#'
+const BLOCKER_SEPARATOR = ', '
+
+function labels_for(is_priority: boolean): ReadonlyArray<string> {
+	const opted_in = [AUTO_OK_LABEL, RUN_LANE_LABEL]
+
+	return is_priority ? [...opted_in, PRIORITY_HIGH_LABEL] : opted_in
+}
+
+// The first label that would not apply, or `undefined` once every one landed. Sequential, so a
+// refused write stops the rest rather than leaving a half-labelled issue the pool reads differently.
+async function first_unapplied(
+	issue: number,
+	labels: ReadonlyArray<string>,
+	ports: AddPorts,
+): Promise<string | undefined> {
+	const [label, ...rest] = labels
+
+	if (label === undefined) return undefined
+
+	if (!(await ports.apply_label(issue, label))) return label
+
+	return await first_unapplied(issue, rest, ports)
+}
+
+async function add_one(issue: number, is_priority: boolean, ports: AddPorts): Promise<AddOutcome> {
+	const view = await ports.read_issue(issue)
+
+	if (view === undefined) return { kind: 'unreadable', issue }
+
+	if (!view.is_open) return { kind: 'closed', issue }
+
+	const label = await first_unapplied(issue, labels_for(is_priority), ports)
+
+	if (label !== undefined) return { kind: 'unlabeled', issue, label }
+
+	return { kind: 'queued', issue, blockers: view.blockers }
+}
+
+// In the order typed, one at a time: the order is the priority, and the reads are a handful of `gh`
+// calls rather than a pool's worth.
+async function add_all(
+	issues: ReadonlyArray<number>,
+	is_priority: boolean,
+	ports: AddPorts,
+): Promise<ReadonlyArray<AddOutcome>> {
+	const [issue, ...rest] = issues
+
+	if (issue === undefined) return []
+
+	const outcome = await add_one(issue, is_priority, ports)
+
+	return [outcome, ...(await add_all(rest, is_priority, ports))]
+}
+
+function additions_of(
+	outcomes: ReadonlyArray<AddOutcome>,
+	is_priority: boolean,
+): ReadonlyArray<CarryAddition> {
+	return outcomes
+		.filter((outcome) => outcome.kind === 'queued')
+		.map((outcome) => ({ issue: outcome.issue, is_priority }))
+}
+
+function blockers_text(blockers: ReadonlyArray<number>): string {
+	return blockers.map((blocker) => `${ISSUE_PREFIX}${String(blocker)}`).join(BLOCKER_SEPARATOR)
+}
+
+function queued_line(issue: string, blockers: ReadonlyArray<number>, is_priority: boolean): string {
+	if (blockers.length > 0) return `queued ${issue} · waiting: blocked by ${blockers_text(blockers)}`
+
+	return `queued ${issue} · ${is_priority ? 'next free lane' : 'end of the queue'}`
+}
+
+// One line per issue, the outcome first, so a reader scanning the output sees which ones went in.
+function describe(outcome: AddOutcome, is_priority: boolean): string {
+	const issue = `${ISSUE_PREFIX}${String(outcome.issue)}`
+
+	if (outcome.kind === 'queued') return queued_line(issue, outcome.blockers, is_priority)
+
+	if (outcome.kind === 'closed') return `refused ${issue} · closed`
+
+	if (outcome.kind === 'unreadable') return `refused ${issue} · could not be read`
+
+	return `refused ${issue} · could not apply \`${outcome.label}\``
+}
+
+function is_all_queued(outcomes: ReadonlyArray<AddOutcome>): boolean {
+	return outcomes.every((outcome) => outcome.kind === 'queued')
+}
+
+const run_add = { add_all, additions_of, describe, is_all_queued, labels_for }
+
+export type { AddOutcome, AddPorts, IssueView }
+export { run_add }

package/scripts/run/board/run-board-cli.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env tsx
+import { setTimeout as sleep } from 'node:timers/promises'
+import { fileURLToPath } from 'node:url'
+import { styleText } from 'node:util'
+import { machine_capacity } from '#scripts/gate/machine-capacity'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { run_progress } from '#scripts/run/progress/run-progress'
+import { run_progress_read } from '#scripts/run/progress/run-progress-read'
+import terminalLink from 'terminal-link'
+import { run_board_closed } from './run-board-closed'
+import { run_board_every } from './run-board-every'
+import { run_board_labels } from './run-board-labels'
+import { run_board_plan } from './run-board-plan'
+import { run_board_read } from './run-board-read'
+import { run_board_screen, type Screen } from './run-board-screen'
+import { run_board_spin } from './run-board-spin'
+import type { BoardPorts } from './run-board-state'
+import { run_board_tick } from './run-board-tick'
+import { run_board_usage_read } from './run-board-usage-read'
+
+// `josh run:board` — a full-screen board of the running `backlogrun`, redrawn once a second, its
+// spinners turned between redraws, for a person to keep open beside the run. What one redraw reads,
+// and how often each read is taken, is `run-board-tick.ts`'s; this file wires the live reads and the
+// terminal around it. A run that ended stays on screen until the next one starts; with no run in this
+// checkout it reads nothing from GitHub and waits.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ONCE_FLAG = '--once'
+const CHAT_FLAG = '--chat'
+const EVERY_FLAG = '--every'
+const FLAGS: ReadonlySet<string> = new Set(['', ONCE_FLAG, CHAT_FLAG])
+const SIGINT_EXIT_CODE = 130
+const SIGTERM_EXIT_CODE = 143
+const USAGE = 'Usage: josh run:board [--once | --chat | --every <minutes>]'
+const DISABLED_NOTICE = `\`${run_progress.DISABLED_KEY}=${run_progress.DISABLED_VALUE}\` is set, so no progress is pushed.`
+const TRAILING_NEWLINE = /\n$/u
+const { FRESH_STATE, tick } = run_board_tick
+const { WORDS } = run_board_labels
+
+// A signal exits with its conventional code, so the `exit` handler restores the screen on every path.
+function on_exit(leave: () => void): void {
+	process.once('exit', leave)
+	process.once('SIGINT', () => process.exit(SIGINT_EXIT_CODE))
+	process.once('SIGTERM', () => process.exit(SIGTERM_EXIT_CODE))
+}
+
+const LIVE_PORTS: BoardPorts = {
+	read_plan: async (scope) => await run_board_plan.read_plan(scope),
+	read_local: run_board_read.read_local,
+	read_machine: machine_capacity.read_sample,
+	read_usage: run_board_usage_read.usage_reader(),
+	read_closed: async (issues) => await run_board_closed.read_all(issues),
+	now: () => Date.now(),
+	write: (frame) => process.stdout.write(frame),
+	// No fallback: a terminal that opens no link, or a pipe, gets the bare number rather than a URL.
+	link: (text, url) => terminalLink(text, url, { fallback: false }),
+	is_tty: process.stdout.isTTY,
+	// Read on every redraw, so a resized pane is fitted on the next one.
+	size: () => ({ rows: process.stdout.rows, columns: process.stdout.columns }),
+	form: 'screen',
+	mark: async () => {
+		run_progress_read.mark(await run_progress_read.stamp_target(), Date.now())
+	},
+	push: async (frame) => {
+		await telegram_notify.progress(frame)
+	},
+	on_exit,
+	sleep: async (ms) => {
+		await sleep(ms)
+	},
+}
+
+// Every frame starts from the top of the alternate screen, erasing what the last one left below it, and
+// ends on the line that says closing the screen leaves the run going — only a screen a person can
+// close says it, and it is the first line to give way to a short pane. Nothing follows the last line,
+// so a frame that fills the pane never scrolls the header off the top.
+function framed(ports: BoardPorts, screen: Screen): BoardPorts {
+	return {
+		...ports,
+		footer: ['', styleText('dim', WORDS.keeps_running)],
+		write: (frame) => {
+			ports.write(`${screen.frame}${frame.replace(TRAILING_NEWLINE, '')}`)
+		},
+	}
+}
+
+// Leaves the alternate screen once, whichever path gets there first: a second leave would restore the
+// cursor saved on entering and draw over whatever was printed after the first.
+function leaver(ports: BoardPorts, screen: Screen): () => void {
+	let has_left = false
+
+	return () => {
+		if (has_left) return
+		has_left = true
+		ports.write(screen.leave)
+	}
+}
+
+// A frame on the second, its spinners turned until the next: the turns are
+// written past the frame's own control bytes, each to its spot on the screen the frame drew.
+async function redraw_forever(ports: BoardPorts, screen: Screen): Promise<void> {
+	const drawn = framed(ports, screen)
+	// The plan is read in the background, so the first frame is drawn without waiting on GitHub.
+	let state = await tick(FRESH_STATE, drawn, 'background')
+
+	for (;;) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each redraw waits for the next second
+		await run_board_spin.spin_to_second(state.spots, ports)
+		// eslint-disable-next-line no-await-in-loop -- polling: each redraw folds the state the last one left
+		state = await tick(state, drawn, 'background')
+	}
+}
+
+// A signal leaves through `on_exit`; a failed redraw leaves before its error is printed, so the error
+// lands on the normal screen rather than vanishing with the alternate one.
+async function watch(ports: BoardPorts): Promise<void> {
+	const screen = run_board_screen.screen_of('live')
+	const leave = leaver(ports, screen)
+
+	ports.write(screen.enter)
+	ports.on_exit(leave)
+
+	try {
+		await redraw_forever(ports, screen)
+	} finally {
+		leave()
+	}
+}
+
+// The answer to a progress question asked during a `backlogrun`: one frame in the chat's form,
+// recorded as the report it is, so the next scheduled one waits a full interval — as
+// `run:progress --once` does.
+async function answer(ports: BoardPorts): Promise<void> {
+	const { text } = await run_board_every.chat_frame(ports)
+
+	ports.write(text)
+	await ports.mark()
+}
+
+function refuse(): number {
+	process.stderr.write(`${USAGE}\n`)
+
+	return FAILURE_EXIT_CODE
+}
+
+// `--every <minutes>`: the chat frame pushed off-screen each interval until the
+// run ends — started only because a person asked, so the heartbeat's no-Telegram rule is untouched.
+async function push_every(minutes: string | undefined, ports: BoardPorts): Promise<number> {
+	const interval = run_progress.minutes_from(minutes)
+
+	if (interval === undefined) return refuse()
+
+	if (run_progress.is_disabled()) {
+		process.stderr.write(`${DISABLED_NOTICE}\n`)
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	await run_board_every.push_until_ended(ports, interval * run_progress.MS_PER_MINUTE)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function draw(flag: string, ports: BoardPorts): Promise<void> {
+	if (flag === CHAT_FLAG) {
+		await answer(ports)
+
+		return
+	}
+
+	const mode = run_board_screen.mode_of({ is_tty: ports.is_tty, is_once: flag === ONCE_FLAG })
+
+	// One plain frame stays on the terminal after the command, so it draws the still icons rather than a
+	// spinner frame frozen mid-turn.
+	const once_ports = { ...ports, is_tty: false, size: undefined }
+
+	await (mode === 'live' ? watch(ports) : tick(FRESH_STATE, once_ports))
+}
+
+function is_every(flag: string, rest: ReadonlyArray<string>): boolean {
+	return flag === EVERY_FLAG && rest.length === 1
+}
+
+function is_refused(flag: string, rest: ReadonlyArray<string>): boolean {
+	return rest.length > 0 || !FLAGS.has(flag)
+}
+
+async function run(argv: ReadonlyArray<string>, ports: BoardPorts = LIVE_PORTS): Promise<number> {
+	const [flag = '', ...rest] = argv
+
+	if (is_every(flag, rest)) return await push_every(rest[0], ports)
+	if (is_refused(flag, rest)) return refuse()
+
+	await draw(flag, ports)
+
+	return SUCCESS_EXIT_CODE
+}
+
+const run_board_cli = { DISABLED_NOTICE, USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+export { run_board_cli }

package/scripts/run/board/run-board-closed.ts

@@ -0,0 +1,95 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_merged } from '#scripts/issue/issue-merged'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { z } from 'zod'
+
+// A child the run touched that has left the open listing, read from GitHub one issue at a time. The
+// listing is the board's only other source of a title, so without this read a board opened after its
+// children closed would draw them nameless, timeless and without saying whether they merged.
+// **A closed issue is read once**: what it answers does not change while it stays closed, so the board
+// keeps the answer for the run and asks GitHub only about children it has not read yet.
+
+interface ClosedIssue {
+	title: string
+	// Its label names, so a closed row still draws its release category (joshuafolkken/kit#3577).
+	labels: ReadonlyArray<string>
+	closed_ms: number | undefined
+	// Closed by a merged pull request, rather than closed by hand.
+	is_merged: boolean
+}
+
+const CLOSED_FIELDS = 'title,state,closedAt,labels'
+const CLOSED_STATE = 'CLOSED'
+const STILL_OPEN = 'open' as const
+
+// What one issue answered: closed, still open, or `undefined` when it could not be read.
+type ClosedRead = ClosedIssue | typeof STILL_OPEN | undefined
+
+// Every issue that answered as closed, and whether every issue answered at all — an ended run stops
+// asking only once a read answered whole, so a transient failure is never kept as still open.
+interface ClosedAnswer {
+	closed: ReadonlyMap<number, ClosedIssue>
+	is_whole: boolean
+}
+
+// The bound `issue:state` reads several issues under, so a run's worth of closed children does not draw
+// GitHub's secondary rate limit.
+const READ_CONCURRENCY = 4
+
+const closed_schema = z.looseObject({
+	title: z.string(),
+	state: z.string(),
+	closedAt: z.string().nullish(),
+	labels: z.array(issue_label_schema).default([]),
+})
+
+type ClosedView = z.infer<typeof closed_schema>
+
+function closed_ms_of(view: ClosedView): number | undefined {
+	const closed_ms = Date.parse(view.closedAt ?? '')
+
+	return Number.isNaN(closed_ms) ? undefined : closed_ms
+}
+
+// `STILL_OPEN` for an issue the listing it was missing from was older than this read; `undefined` for one
+// whose issue or timeline could not be read. Either is asked again on the next read, so a transient
+// failure is never kept as closed-not-merged.
+async function read_closed(issue: number): Promise<ClosedRead> {
+	const json = await git_gh_issue_read.issue_view_json(String(issue), CLOSED_FIELDS)
+	const view = json === undefined ? undefined : parse_json_object_or_undefined(json, closed_schema)
+
+	if (view === undefined) return undefined
+	if (view.state !== CLOSED_STATE) return STILL_OPEN
+
+	const is_merged = await issue_merged.read_merge_state(String(issue))
+
+	if (is_merged === undefined) return undefined
+
+	const labels = view.labels.map((label) => label.name)
+
+	return { title: view.title, labels, closed_ms: closed_ms_of(view), is_merged }
+}
+
+async function read_all(
+	issues: ReadonlyArray<number>,
+	read: (issue: number) => Promise<ClosedRead> = read_closed,
+): Promise<ClosedAnswer> {
+	const answers = await bounded_pool.bounded_map(issues, READ_CONCURRENCY, async (issue) => ({
+		issue,
+		answer: await read(issue),
+	}))
+	const closed = new Map(
+		answers.flatMap(({ issue, answer }) =>
+			typeof answer === 'object' ? [[issue, answer] as const] : [],
+		),
+	)
+
+	return { closed, is_whole: answers.every(({ answer }) => answer !== undefined) }
+}
+
+const run_board_closed = { STILL_OPEN, read_all, read_closed }
+
+export { run_board_closed }
+export type { ClosedAnswer, ClosedIssue }

package/scripts/run/board/run-board-every.ts

@@ -0,0 +1,60 @@
+import { stripVTControlCharacters } from 'node:util'
+import type { LocalRead } from './run-board-read'
+import type { BoardPorts } from './run-board-state'
+import { run_board_tick } from './run-board-tick'
+
+// The chat frame `run:board --chat` answers with, and `--every <minutes>`, which pushes that same frame
+// off-screen on a schedule with no model in between. The frame needs no model, so a plain background
+// process sends it and ends with the run, rather than a scheduled session re-reading its whole context.
+
+const { FRESH_STATE, tick } = run_board_tick
+
+interface ChatFrame {
+	text: string
+	// The run the frame drew; `undefined` when none has started here.
+	local: LocalRead | undefined
+}
+
+// One frame in the chat's form, with every escape stripped because a chat shows them as text.
+async function chat_frame(ports: BoardPorts): Promise<ChatFrame> {
+	let text = ''
+	const chat_ports: BoardPorts = {
+		...ports,
+		is_tty: false,
+		size: undefined,
+		form: 'chat',
+		write: (frame) => {
+			text += stripVTControlCharacters(frame)
+		},
+	}
+	const { local } = await tick(FRESH_STATE, chat_ports)
+
+	return { text, local }
+}
+
+// Pushes one frame, answering whether the run is still going: no run sends nothing, and an ended run's
+// frame is the last one sent.
+async function push_one(ports: BoardPorts): Promise<boolean> {
+	const { text, local } = await chat_frame(ports)
+
+	if (local === undefined) return false
+
+	await ports.push(text)
+
+	return local.ended_ms === undefined
+}
+
+async function push_until_ended(ports: BoardPorts, interval_ms: number): Promise<void> {
+	let is_running = await push_one(ports)
+
+	while (is_running) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each push waits out the interval
+		await ports.sleep(interval_ms)
+		// eslint-disable-next-line no-await-in-loop -- polling: each push reads the run afresh
+		is_running = await push_one(ports)
+	}
+}
+
+const run_board_every = { chat_frame, push_until_ended }
+
+export { run_board_every }

package/scripts/run/board/run-board-fetch.ts

@@ -0,0 +1,38 @@
+// A GitHub read in flight. The plan and the closed children are queries that
+// take seconds, so a live board launches each and goes on redrawing; the read keeps its answer once it
+// lands, and the next redraw folds it in. A rejected read answers with the value given for a failed one
+// — nothing awaits a background read to see it throw.
+
+// `undefined` while the read is in flight.
+interface Answer<T> {
+	value: T
+}
+
+interface Fetch<T> {
+	// Settles once the read has answered, never rejecting — what a board that waits for a read awaits.
+	landed: Promise<void>
+	answer: () => Answer<T> | undefined
+}
+
+async function answer_of<T>(read: () => Promise<T>, failed: T): Promise<Answer<T>> {
+	try {
+		return { value: await read() }
+	} catch {
+		return { value: failed }
+	}
+}
+
+function launch<T>(read: () => Promise<T>, failed: T): Fetch<T> {
+	const box: { answer: Answer<T> | undefined } = { answer: undefined }
+
+	async function land(): Promise<void> {
+		box.answer = await answer_of(read, failed)
+	}
+
+	return { landed: land(), answer: () => box.answer }
+}
+
+const run_board_fetch = { launch }
+
+export { run_board_fetch }
+export type { Fetch }