jackherd 0.0.1 → 1.0.1

package/src/plans/selection.ts

@@ -0,0 +1,352 @@
+import { currentPhase, type LaneProgress } from '../plan-format'
+import { AGENT_STATUS } from '../terminal/types'
+import { chipUrlOf, isChipKey, planUrlOf } from './link-chips'
+
+/**
+ * Whether a lane is drawn open, and the agent status that was true when that was decided. The fold
+ * counts only while the lane still has that status: a change of status hands the decision back to
+ * the automatic rule (`autoOpen`), so a lane that starts working opens by itself even if a person closed it.
+ */
+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.
+ */
+export type Selection = {
+  selected: string | null
+  expanded: ReadonlySet<string>
+  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. */
+export type LaneStatusEntry = { lane: string; status: string | null }
+
+/** What the screen shows: the selection, the first visible body line, and whether the window follows the cursor. */
+export type View = { selection: Selection; top: number; follow: boolean }
+
+/** What an input needs to know about the frame on screen. */
+export type InputContext = {
+  keys: readonly string[]
+  targets: readonly ClickTarget[]
+  headerRows: number
+  bodyRows: number
+}
+
+/** A clickable span of a frame line, columns 0-based and `to` exclusive. */
+export type ClickTarget = { line: number; from: number; to: number; key: string }
+
+/** An SGR mouse report; column and row are 1-based as the terminal sends them. */
+export type MouseEvent = { button: number; column: number; row: number; pressed: boolean }
+
+export const INPUT = {
+  up: ['\x1b[A', '\x1bOA', 'k'],
+  down: ['\x1b[B', '\x1bOB', 'j'],
+  toggle: ['\r', ' '],
+  expand: ['\x1b[C', '\x1bOC', 'l'],
+  collapse: ['\x1b[D', '\x1bOD', 'h'],
+  showDone: ['a'],
+  legend: ['?'],
+  notes: ['n'],
+  sprintPage: ['s'],
+  pageUp: ['\x1b[5~'],
+  pageDown: ['\x1b[6~'],
+} as const
+
+const WHEEL_LINES = 3
+
+const ESC = '\x1b'
+const ESCAPE_SEQUENCE = new RegExp(`${ESC}(?:\\[[<0-9;]*[A-Za-z~]|O[A-Za-z])|[\\s\\S]`, 'gu')
+const MOUSE_REPORT = new RegExp(`^${ESC}\\[<(\\d+);(\\d+);(\\d+)([Mm])$`)
+
+const MOUSE_BUTTON = { left: 0, wheelUp: 64, wheelDown: 65 } as const
+
+/** One terminal read can carry several key presses; this splits it into keys, escape sequences kept whole. */
+export const splitKeys = (chunk: string): string[] => chunk.match(ESCAPE_SEQUENCE) ?? []
+
+/** The key of the closing row that lists the planned phases; no lane key starts without `@`, no phase key lacks a colon. */
+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}`
+
+/** The key of the "N ticked" line of an open phase; it is clicked only, and a click lands on the phase. */
+export const tickedKey = (phase: string): string => `${TICKED_KEY_PREFIX}${phase}`
+
+const ITEM_KEY = /^(.+:\d+:[^:#]+)#(\d+)$/
+
+/**
+ * The key of a task row: its phase's key and the task's index in `phase.items`; a click or Enter opens its text.
+ * The index counts the checkboxes of the phase, so a checkbox inserted above a task shifts which task an open
+ * key names after the plan is reloaded; a task stays open by position, not by text.
+ */
+export const itemKey = (phase: string, index: number): string => `${phase}#${index}`
+
+/** 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
+
+const LANE_KEY_PREFIX = '@'
+
+/** The key of a lane's own row; it cannot collide with a phase key, which starts with a lane name and a colon. */
+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
+
+/** Whether a lane is drawn open: the person's choice while its status is unchanged, else the automatic rule. */
+export const isLaneOpen = ({ laneFolds }: Selection, lane: string, status: string | null): boolean => {
+  const fold = laneFolds.get(lane)
+  return fold && fold.status === status ? fold.open : autoOpen(status)
+}
+
+/**
+ * Lets the folds follow the lanes: a lane keeps its fold while its status is the same, gets the
+ * automatic one when its status changed or it is new, and loses it when it left the sprint. Returns
+ * the same object when nothing changed.
+ */
+export const syncLaneFolds = (selection: Selection, lanes: readonly LaneStatusEntry[]): Selection => {
+  const folds = new Map<string, LaneFold>()
+  for (const { lane, status } of lanes) {
+    const fold = selection.laneFolds.get(lane)
+    folds.set(lane, fold && fold.status === status ? fold : { status, open: autoOpen(status) })
+  }
+  const unchanged =
+    folds.size === selection.laneFolds.size &&
+    [...folds].every(([lane, fold]) => selection.laneFolds.get(lane) === fold)
+  return unchanged ? selection : { ...selection, laneFolds: folds }
+}
+
+export const overviewSelection = (): Selection => ({
+  selected: null,
+  expanded: new Set(),
+  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. */
+export const laneSelection = (progress: LaneProgress | undefined, status: string | null): Selection => {
+  const base = overviewSelection()
+  if (!progress) return base
+  const opened = { ...base, laneFolds: new Map([[progress.lane.name, { status, open: true }]]) }
+  const phase = currentPhase(progress)
+  if (!progress.current || !phase) return opened
+  const key = phaseKey(progress.lane.name, progress.current.stepIndex, phase.id)
+  return { ...opened, selected: key, expanded: new Set([key]) }
+}
+
+/** The selectable rows in screen order, once each: only what is drawn can be selected; a chip or a "N ticked" line is clicked, not selected. */
+export const targetKeys = (targets: readonly ClickTarget[]): string[] => [
+  ...new Set(targets.map((target) => target.key).filter((key) => !isChipKey(key) && tickedPhaseOfKey(key) === null)),
+]
+
+/** The selected key, or the first one while nothing is selected or the selected phase left the sprint. */
+export const selectedKey = ({ selected }: Selection, keys: readonly string[]): string | null =>
+  selected && keys.includes(selected) ? selected : (keys[0] ?? null)
+
+const isInput = (group: readonly string[], input: string): boolean => group.includes(input)
+
+const move = (selection: Selection, keys: readonly string[], step: number): Selection => {
+  const current = selectedKey(selection, keys)
+  const index = current ? keys.indexOf(current) : 0
+  const next = keys[Math.min(Math.max(index + step, 0), keys.length - 1)] ?? null
+  return { ...selection, selected: next }
+}
+
+const toggleIn = (keys: Set<string>, key: string): void => {
+  if (!keys.delete(key)) keys.add(key)
+}
+
+const opened = () => true
+const closed = () => false
+const flipped = (open: boolean) => !open
+
+/** Changes the fold of a lane; a lane without a fold is left alone, which `syncLaneFolds` rules out once a snapshot is loaded. */
+const foldLane = (selection: Selection, lane: string, next: (open: boolean) => boolean): Selection => {
+  const fold = selection.laneFolds.get(lane)
+  if (!fold) return selection
+  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)
+  expanded.add(task)
+}
+
+/** 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)
+  if (lane !== null) return { ...foldLane(selection, lane, flipped), selected: key }
+  const expanded = new Set(selection.expanded)
+  const itemPhase = itemPhaseOfKey(key)
+  if (itemPhase !== null && !expanded.has(itemPhase)) openTaskWithPhase(expanded, itemPhase, key)
+  else toggleIn(expanded, key)
+  return { ...selection, selected: key, expanded }
+}
+
+const toggle = (selection: Selection, keys: readonly string[]): Selection => {
+  const current = selectedKey(selection, keys)
+  return current ? applyClick(selection, current) : 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)
+  if (next(expanded.has(current))) {
+    expanded.add(current)
+    const itemPhase = itemPhaseOfKey(current)
+    if (itemPhase !== null) expanded.add(itemPhase)
+  } else expanded.delete(current)
+  return { ...selection, selected: current, expanded }
+}
+
+const expand = (selection: Selection, keys: readonly string[]): Selection => changeSelected(selection, keys, opened)
+
+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)
+  if (isInput(INPUT.toggle, input)) return toggle(selection, keys)
+  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
+}
+
+/** The key that writes the whole sprint as an HTML page and opens it. */
+export const isSprintPageKey = (input: string): boolean => isInput(INPUT.sprintPage, input)
+
+export const parseMouse = (key: string): MouseEvent | null => {
+  const match = key.match(MOUSE_REPORT)
+  if (!match) return null
+  return { button: Number(match[1]), column: Number(match[2]), row: Number(match[3]), pressed: match[4] === 'M' }
+}
+
+export const targetAt = (targets: readonly ClickTarget[], line: number, column: number): string | null =>
+  targets.find((target) => target.line === line && column >= target.from && column < target.to)?.key ?? null
+
+const scrollDelta = (input: string, mouse: MouseEvent | null, bodyRows: number): number => {
+  if (mouse?.button === MOUSE_BUTTON.wheelUp) return -WHEEL_LINES
+  if (mouse?.button === MOUSE_BUTTON.wheelDown) return WHEEL_LINES
+  if (isInput(INPUT.pageUp, input)) return -Math.max(bodyRows - 1, 1)
+  if (isInput(INPUT.pageDown, input)) return Math.max(bodyRows - 1, 1)
+  return 0
+}
+
+const clicked = (mouse: MouseEvent, view: View, { targets, headerRows }: InputContext): string | null => {
+  if (!mouse.pressed || mouse.button !== MOUSE_BUTTON.left) return null
+  return targetAt(targets, view.top + mouse.row - 1 - headerRows, mouse.column - 1)
+}
+
+/**
+ * Applies one key or mouse report. Wheel and page keys move the window and stop it following the
+ * cursor; everything that changes the selection makes it follow again.
+ */
+export const applyInput = (view: View, input: string, context: InputContext): View => {
+  const mouse = parseMouse(input)
+  const delta = scrollDelta(input, mouse, context.bodyRows)
+  if (delta !== 0) return { ...view, top: Math.max(view.top + delta, 0), follow: false }
+  const key = mouse ? clicked(mouse, view, context) : null
+  if (mouse)
+    return key && !isChipKey(key) ? { ...view, selection: applyClick(view.selection, key), follow: true } : view
+  const selection = applyKey(view.selection, input, context.keys)
+  return selection === view.selection ? view : { ...view, selection, follow: true }
+}
+
+/** The row an input acts on: enter, space or right on the selected row, or a left click; null for anything else. */
+export const activatedKey = (view: View, input: string, context: InputContext): string | null => {
+  const mouse = parseMouse(input)
+  if (mouse) return clicked(mouse, view, context)
+  const activates = isInput(INPUT.toggle, input) || isInput(INPUT.expand, input)
+  return activates ? selectedKey(view.selection, context.keys) : null
+}
+
+/**
+ * What one input does: a click on a chip asks to open its link and leaves the selection alone; activating a row
+ * that has a link (a pull request) selects it and asks to open the link; every other input goes through `applyInput`. `linkOf` answers the link behind a row key.
+ */
+export const inputOutcome = (
+  view: View,
+  input: string,
+  context: InputContext,
+  linkOf: (key: string) => string | null,
+): { view: View; open: string | null } => {
+  const activated = activatedKey(view, input, context)
+  const chipUrl = activated ? (chipUrlOf(activated) ?? planUrlOf(activated)) : null
+  if (chipUrl) return { view, open: chipUrl }
+  const link = activated ? linkOf(activated) : null
+  if (!link) return { view: applyInput(view, input, context), open: null }
+  return { view: { ...view, selection: { ...view.selection, selected: activated }, follow: true }, open: link }
+}
+
+/** The first visible body line: following the cursor, or where the user scrolled, never past the last line. */
+export const windowTop = (view: View, cursorLine: number, lineCount: number, rows: number): number =>
+  view.follow && cursorLine >= 0
+    ? scrollTop(view.top, cursorLine, lineCount, rows)
+    : Math.min(view.top, Math.max(lineCount - rows, 0))
+
+/** The first visible line of a window of `rows` lines that keeps `cursorLine` in view, moving as little as it can. */
+export const scrollTop = (top: number, cursorLine: number, lineCount: number, rows: number): number => {
+  const followed = cursorLine < top ? cursorLine : cursorLine >= top + rows ? cursorLine - rows + 1 : top
+  return Math.min(followed, Math.max(lineCount - rows, 0))
+}

package/src/plans/settings.ts

@@ -0,0 +1,68 @@
+import { homedir } from 'node:os'
+import { join, relative } from 'node:path'
+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'
+
+export const CONFIG_PATH = PROJECT_CONFIG_PATH
+
+export type PlansSettings = Pick<
+  JackherdConfig,
+  'planDirectory' | 'board' | 'worktreeDirectory' | 'baseBranch' | 'planLanguage' | 'responseLanguage'
+> & {
+  adapter: JackherdConfig['terminal']['adapter']
+  fetchIntervalMinutes: number
+  linkKinds: JackherdConfig['plans']['linkKinds']
+  context: JackherdConfig['plans']['context']
+}
+
+const CLOCK_LOCALE: Record<PlanLanguage, string> = {
+  [PLAN_LANGUAGE.de]: 'de-DE',
+  [PLAN_LANGUAGE.en]: 'en-GB',
+}
+
+/** The plans view's slice of a validated config. */
+export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
+  planDirectory: config.planDirectory,
+  board: config.board,
+  worktreeDirectory: config.worktreeDirectory,
+  baseBranch: config.baseBranch,
+  planLanguage: config.planLanguage,
+  responseLanguage: config.responseLanguage,
+  adapter: config.terminal.adapter,
+  fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
+  linkKinds: config.plans.linkKinds,
+  context: config.plans.context,
+})
+
+/** The plans view'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. */
+export const boardGlobOf = (settings: PlansSettings): string =>
+  `${settings.planDirectory}/${settings.board.pattern}/${settings.board.file}`
+
+/**
+ * A board file's path in the repository: relative to the main checkout `root`, or, for a board inside a lane's
+ * worktree under `worktreeDirectory`, relative to that worktree. Both name the same file on the base branch.
+ */
+export const boardRepoPathOf = (root: string, settings: PlansSettings, file: string): string => {
+  const path = relative(root, file)
+  const prefix = `${settings.worktreeDirectory}/`
+  return path.startsWith(prefix) ? path.slice(prefix.length).split('/').slice(1).join('/') : path
+}
+
+export const worktreeOf = (root: string, settings: PlansSettings, laneName: string): string =>
+  join(root, settings.worktreeDirectory, laneName)
+
+/** The remote whose base branch the view reads plans and the board from. */
+export const BASE_REMOTE = 'origin'
+
+export const baseRefOf = ({ baseBranch }: Pick<PlansSettings, 'baseBranch'>): string => `${BASE_REMOTE}/${baseBranch}`
+
+export const clockLocaleOf = (settings: PlansSettings): string => CLOCK_LOCALE[settings.responseLanguage]
+
+/** The plans view's settings from the config `readConfig` finds. */
+export const readSettings = (roots: string[], home: string = homedir()): PlansSettings =>
+  plansSettingsOf(readConfig(roots, home))

package/src/plans/single-flight.ts

@@ -0,0 +1,25 @@
+/**
+ * Runs `task` one at a time. A call made while it runs does not start a second one alongside: it is remembered,
+ * and the task runs once more when the first has finished, however many calls came meanwhile. Every caller's
+ * promise settles when the run it asked for is done.
+ */
+export const singleFlight = (task: () => Promise<void>): (() => Promise<void>) => {
+  let running: Promise<void> | null = null
+  let again = false
+  const run = async (): Promise<void> => {
+    do {
+      again = false
+      await task()
+    } while (again)
+  }
+  return () => {
+    if (running !== null) {
+      again = true
+      return running
+    }
+    running = run().finally(() => {
+      running = null
+    })
+    return running
+  }
+}