jackherd 1.9.0 → 1.11.0

package/src/plans/supervisor.ts

@@ -4,6 +4,7 @@ import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { pendingKitUpdate, VERSION_POLL_MS } from '../version/installed-version'
 import type { StartedKit } from '../version/started-kit'
+import { STOP_REQUEST, type Stopper, stopperOf } from './child-stop'
 import { HERD_COMMAND } from './herd-command'
 import { CHILD_MARKER, exitCodeOf, isRestartTrigger, nextStep, RESTART_DEBOUNCE_MS } from './restart-decision'
 import { TERMINAL_OFF } from './view'
@@ -30,7 +31,8 @@ const spawnView = (scriptPath: string, args: string[]): ChildProcess =>
 /**
  * Runs the live view as a child process and restarts it when the package's own source changes,
  * so a long-lived `plans` never shows the behaviour of code that has since been edited. The child
- * stops on SIGTERM through the handler that restores the terminal. Resolves with the exit code
+ * stops on SIGTERM through the handler that restores the terminal, and is killed when it does not end within
+ * `GRACE_MS` (a restart included); a second signal while stopping kills it at once. Resolves with the exit code
  * of a wanted end only: the child's clean exit (`q`) or a signal forwarded to it. A child that
  * dies otherwise leaves the supervisor waiting, with the terminal restored, for the next change
  * to `src/`, which spawns a fresh child. `kit` is the package this process loaded (null when it cannot be
@@ -45,6 +47,7 @@ export const superviseView = (
 ): Promise<number> =>
   new Promise((resolveExit) => {
     let child: ChildProcess | undefined
+    let stopper: Stopper | undefined
     let restarting = false
     let stopping = false
     let timer: ReturnType<typeof setTimeout> | undefined
@@ -66,6 +69,12 @@ export const superviseView = (
     const start = (isFirst: boolean): void => {
       const current = spawnView(scriptPath, args)
       child = current
+      const currentStopper = stopperOf({
+        kill: (signal) => current.kill(signal),
+        setTimer: (run, ms) => setTimeout(run, ms),
+        clearTimer: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+      })
+      stopper = currentStopper
 
       current.on('error', (error) => {
         if (child !== current) return
@@ -79,6 +88,7 @@ export const superviseView = (
       })
 
       current.on('exit', (code, signal) => {
+        currentStopper.ended()
         if (child !== current) return
         const context = { restarting, stopping, code, signal }
         restarting = false
@@ -94,7 +104,7 @@ export const superviseView = (
     const restartView = (): void => {
       if (child) {
         restarting = true
-        child.kill('SIGTERM')
+        stopper?.request('SIGTERM')
       } else start(false)
     }
 
@@ -118,8 +128,8 @@ export const superviseView = (
         stopping = true
         clearTimeout(timer)
         clearInterval(versionTimer)
-        if (child) child.kill(signal)
-        else finish(exitCodeOf(null, signal))
+        if (!child || !stopper) finish(exitCodeOf(null, signal))
+        else if (stopper.request(signal) === STOP_REQUEST.killed) finish(exitCodeOf(null, signal))
       })
     }
   })

package/src/plans/symbols.ts

@@ -21,6 +21,9 @@ export const statusWord = (agent: string | null): string => agent ?? NO_AGENT_WO
 /** Before a row that opens and closes: lanes, the planned phases, the ticked items of a phase. */
 export const CHEVRON = { closed: '▸', open: '▾' } as const
 
+/** Before the count under a block that shows all its rows; a click folds it back to five. */
+export const LESS_MARK = '▴'
+
 export const chevronOf = (open: boolean): string => (open ? CHEVRON.open : CHEVRON.closed)
 
 export const PHASE_STATE = { missing: 'missing', empty: 'empty', all: 'all', open: 'open' } as const

package/src/plans/task-name.ts

@@ -0,0 +1,34 @@
+const TASK_NAME = /^\*\*([^*]+)\*\*:/
+
+const TITLE_END = ': '
+
+const titleEndOf = (text: string): number => {
+  let inCode = false
+  for (let index = 0; index < text.length; index++) {
+    if (text[index] === '`') inCode = !inCode
+    else if (!inCode && text.startsWith(TITLE_END, index)) return index
+  }
+  return -1
+}
+
+/**
+ * The text up to its first colon followed by a space outside backticks, as a folded row shows it; the text as it is
+ * without such a colon or with nothing before it. A time like `18:55` has no space after its colon and does not split.
+ */
+export const shortTitle = (text: string): string => {
+  const end = titleEndOf(text)
+  return end > 0 ? text.slice(0, end) : text
+}
+
+/**
+ * The short name a task carries in bold at its start, `**Name**: content`, as written; null for a line without one.
+ * Nothing is guessed from the text up to its first colon: a path at the start of a line would read as a name.
+ */
+export const taskNameOf = (text: string): string | null => {
+  const name = text.match(TASK_NAME)?.[1]?.trim()
+  return name ? name : null
+}
+
+/** The text after a task's `**Name**:`, as an opened task shows it under its name; the text as it is without a name. */
+export const taskBodyOf = (text: string): string =>
+  taskNameOf(text) === null ? text : text.replace(TASK_NAME, '').trimStart()

package/src/plans/texts.ts

@@ -1,13 +1,14 @@
 import { STALE_ACTIVITY_MINUTES } from './lane-summary'
+import { STALE_PLAN_DAYS } from './planned'
 import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from './pull-requests'
 import { shownWithMore } from './shown-with-more'
 import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
 
-/** The words of an open lane: the age of a running phase, the word before the open phases that wait, the finished phases not merged yet, and the pointer of a phase with only its review gate open. */
+/** The words of an open lane: the age of a running phase, the words before the open phases that wait and the finished ones, and the pointer of a phase with only its review gate open. */
 export type HerdTexts = {
   minutesAgo: (minutes: number) => string
   next: string
-  notMerged: string
+  done: string
   reviewGate: string
   gate: string
 }
@@ -23,20 +24,45 @@ export type PlanTexts = {
   noPlan: string
   noWorktree: string
   noRow: string
+  /** The heads of the blocks on top of the herd. */
+  waitingHeading: string
+  appointmentHeading: string
+  sourceHeading: string
+  nextHeading: string
+  /** On a resting lane's line: the label before its starts-after cell, and the line for a lane without any reason. */
+  restAfter: string
+  restNoReason: string
+  /** After the head of the next block when the board's section holds no line. */
+  nextEmpty: string
   notInPlan: string
   /** Before a task an agent reports that no task of the plan names. */
   now: string
+  /** Before the description of a running subagent that names no phase and sits on none. */
+  subagent: string
   /** In place of the count of a phase whose only open box is the documentation box of its review gate. */
   allButDocs: string
   tickedSummary: (count: number) => string
+  /** The line above the listed ticked tasks of a phase; a click or `a` folds them again. */
+  tickedFold: (count: number) => string
   draft: string
   privateLink: string
   planned: (phases: number, plans: number) => string
+  /** The head of the planned section in the herd: `planned · 3 plans, next:`. */
+  plannedHead: (plans: number) => string
   phaseTally: (done: number, total: number) => string
   herd: HerdTexts
   checks: Record<ChecksState, string>
   hint: string
+  /** The notice when `a` is pressed with no phase open, where the key changes nothing on screen. */
+  showDoneNeedsPhase: string
   legend: string[]
+  /** The footer line when the coordinator could not be asked to put a question, with the reason. */
+  notAsked: (reason: string) => string
+  /** The footer line when the coordinator `name` was asked to put `subject`, `question <id>` or `board row <key>`. */
+  asked: (name: string, subject: string) => string
+  /** The footer line after `[done]` closed `subject`, and the one with the reason when it could not. */
+  closed: (subject: string) => string
+  notClosed: (reason: string) => string
 }
 
 /** The words of the watcher's badges and of the header notice when they are missing. */
@@ -78,38 +104,54 @@ export const TEXTS: PlanTexts = {
   noPlan: 'no plan',
   noWorktree: 'no worktree',
   noRow: 'no row in lanes',
+  waitingHeading: 'Waiting for you',
+  appointmentHeading: 'Appointments',
+  sourceHeading: 'Sources',
+  nextHeading: 'Next',
+  restAfter: 'after:',
+  restNoReason: 'idle · no reason',
+  nextEmpty: 'nothing queued, groom the board',
   notInPlan: 'not in the plan',
   now: 'now:',
+  subagent: 'Subagent:',
   allButDocs: ALL_BUT_DOCS,
   tickedSummary: (count) => `${count} ticked · click or a lists them`,
+  tickedFold: (count) => `${count} ticked · click or a folds them`,
   draft: 'draft · ',
   privateLink: 'private',
   phaseTally: (done, total) => (total > 0 ? `${done}/${total} ph` : ''),
   herd: {
     minutesAgo: (minutes) => (minutes === 0 ? '· just now' : `· ${minutes} min ago`),
     next: 'next',
-    notMerged: 'not merged',
+    done: 'done',
     reviewGate: 'Review gate',
     gate: '· gate',
   },
   planned: (phases, plans) =>
     `planned (${phases} ${phases === 1 ? 'phase' : 'phases'} in ${plans} ${plans === 1 ? 'plan' : 'plans'})`,
+  plannedHead: (plans) => `planned · ${plans} ${plans === 1 ? 'plan' : 'plans'}, next:`,
   checks: {
     [CHECKS.passed]: '✓ checks',
     [CHECKS.failed]: '✗ checks',
     [CHECKS.pending]: '… checks',
     [CHECKS.none]: 'no checks',
   },
-  hint: '↑↓ select  →← open  a show ticked  s html  q quit  ? help',
+  hint: '↑↓ select  →← open  a/click ticked tasks  s html  q quit  ? help',
+  showDoneNeedsPhase: 'a lists the ticked tasks inside an open phase: open one with → or a click',
   legend: [
     'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a link chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
     '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · • state unknown · only blocked wears its word in the lane line, the symbol says the rest · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · a working or blocked lane opens by itself only when it first appears, after that → ← and clicks are yours alone',
-    `▸ ▾ open and close · an open lane's branches, top down: the agent's title and ⎇ its branch, ↗ its pull requests, its link chips, the phases it works on, next, ✓ · a lane shows only the phases its board rows name · a phase row = some of its tasks are ticked, one of its boxes was ticked in the last ${STALE_ACTIVITY_MINUTES} min, or an agent reports working on it, by number · n min ago since the last tick or report, · gate = only the review gate is open · ▶ teal = a task an agent reported (its task list or jh task; its name dim at the right edge when several agents work in the lane), ▷ dim = only guessed from the words of its log · now: <text> = a reported task no plan task names · next = the other open phases, as ranges · ✓ the finished ones, not merged = ticked in the worktree, not on the base branch yet · ${ALL_BUT_DOCS} = only the documentation box is open · a folded lane line names the phase moved last, +n more active ones, and its count · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes one by one · s opens every lane and plan as one HTML page`,
+    `▸ ▾ open and close · an open lane's branches, top down: the agent's title and ⎇ its branch, ↗ its pull requests, its link chips, the phases it works on, next, done · a lane shows only the phases its board rows name · a phase row = some of its tasks are ticked, one of its boxes was ticked in the last ${STALE_ACTIVITY_MINUTES} min, or an agent reports working on it, by number · n min ago since the last tick or report, · gate = only the review gate is open · ▶ teal = a task an agent reported (its task list or jh task; its name dim at the right edge when several agents work in the lane), ▷ dim = only guessed from the words of its log · now: <text> = a reported task no plan task names · a running review sits on the gate box that names it, in the phase it names or else the lane's current one · Subagent: <text> = a running subagent that names no phase and sits on none · next = the other open phases, as ranges · done = the finished ones · ${ALL_BUT_DOCS} = only the documentation box is open · a folded lane line names the phase moved last, +n more active ones, and its count · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a or a click on its ▸ n ticked line lists the ticked checkboxes of an open phase one by one, a or a click on its ▾ line folds them · s opens every lane and plan as one HTML page`,
     `the bar = progress over the lane's plans · n/m = m checkboxes, n ticked · n/m ph = n of m phases finished · n/n in green = all ticked · 🥣 share of the context window used, on a folded lane only once it warns · Sonnet ${MODEL_MARK.differs} Opus in amber = the phase's subagent ran on another model than the plan's`,
     '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status among the link chips, 📡 <n> in amber on a folded lane when tickets are new',
-    '▌ on top = waits for your answer: 📎 a file or an Artifact that was sent (click: a cut-off row expands, then it opens), ? a question of the board · it goes when the board row is closed or `jh waiting close <id>` · woof closes the block',
+    `▌ on top = waits for your answer: 📎 a file or an Artifact that was sent (click: a cut-off row expands, then it opens), ? a question of the board or one a session left in its dialog (a click on its text only expands and folds it; [ask] at the right edge of a question asks the coordinator to put it; [done] closes the row: a board row gets its status, a sent file its record) · it goes when the board row is closed or \`jh waiting close <id>\` · \`Waiting for you\` heads the block (click: fold; click on +n: show all, on ▴ n: five) · ◷ the appointments of the board in a grey bar below it (click: fold; [done] closes the row, [run] asks the coordinator to run it now, [move] to ask you for a new time) · 1 2 3 = Next, the board lines to do next · ● Sources = the watcher’s sources that are no tickets: when each ran and its newest report, the mark amber while that report is under a day old and red while the source fails (click on a row: opens the entry) · planned = the open phases no lane works on, the next one per plan; stale? = its plan file was not changed on the base branch for ${STALE_PLAN_DAYS} days`,
     '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
+    '❯ and a light background = the row under the mouse or the arrows, on every clickable row · enter on a block row asks, opens or expands it and never presses [done] · [xx] in square brackets = a click does something, bold under the mouse',
   ],
+  notAsked: (reason) => `no coordinator to ask: ${reason}`,
+  asked: (name, subject) => `asked ${name} for ${subject}`,
+  closed: (subject) => `closed ${subject}`,
+  notClosed: (reason) => `not closed: ${reason}`,
 }
 
 /** The mark of a running lane the board has no row for; null for a lane it lists. */

package/src/plans/tones.ts

@@ -0,0 +1,30 @@
+import { DEFAULT_TONES, TONE, type ToneName, type ToneRole } from '../config/tones'
+import { paint } from '../terminal/text'
+
+const TONE_PAINT: Record<ToneName, (text: string) => string> = {
+  [TONE.amber]: paint.yellow,
+  [TONE.teal]: paint.teal,
+  [TONE.grey]: paint.dim,
+  [TONE.red]: paint.red,
+  [TONE.green]: paint.green,
+  [TONE.blue]: paint.blue,
+  [TONE.magenta]: paint.magenta,
+}
+
+let palette: Record<ToneRole, ToneName> = DEFAULT_TONES
+
+/**
+ * Sets the tone of each role for the screens drawn from now on. The herd calls it once per frame with the config's
+ * tones, so the layout reads one palette and no function of it takes the colours as a parameter.
+ */
+export const setTones = (tones: Record<ToneRole, ToneName>): void => {
+  palette = tones
+}
+
+export const paintOfTone = (name: ToneName): ((text: string) => string) => TONE_PAINT[name]
+
+/** The paint of a role in the palette set last. */
+export const paintOfRole = (role: ToneRole): ((text: string) => string) => TONE_PAINT[palette[role]]
+
+/** The tone name of a role in the palette set last. */
+export const toneOfRole = (role: ToneRole): ToneName => palette[role]

package/src/plans/view.ts

@@ -1,16 +1,19 @@
+import { ARTIFACT_LINK_KIND } from '../config/link-kinds'
+import { DEFAULT_TONES } from '../config/tones'
 import { fit, plainText } from '../terminal/text'
 import { renderSelected, type Screen } from './layout'
 import type { Options } from './options'
 import { laneSelection, overviewSelection, type Selection } from './selection'
 import type { Snapshot } from './snapshot'
+import { setTones } from './tones'
 
 const DEFAULT_WIDTH = 100
 const CURSOR_HOME = '\x1b[H'
 const CLEAR_LINE_END = '\x1b[K'
 const CLEAR_BELOW = '\x1b[J'
 
-export const TERMINAL_ON = '\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h'
-export const TERMINAL_OFF = '\x1b[?1006l\x1b[?1000l\x1b[?25h\x1b[?1049l'
+export const TERMINAL_ON = '\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1003h\x1b[?1006h'
+export const TERMINAL_OFF = '\x1b[?1006l\x1b[?1003l\x1b[?1000l\x1b[?25h\x1b[?1049l'
 
 /** One column short of the pane: a line filling the last column makes some terminals wrap it. */
 export const paneWidth = (): number => (process.stdout.columns ?? (Number(process.env.COLUMNS) || DEFAULT_WIDTH)) - 1
@@ -20,7 +23,9 @@ const paneRows = (): number => process.stdout.rows ?? Number.MAX_SAFE_INTEGER
 export const bodyRows = (screen: Screen): number =>
   Math.max(paneRows() - screen.header.length - screen.footer.length, 1)
 
-export const clockOf = (locale: string): string => new Date().toLocaleTimeString(locale)
+/** The time as `HH:MM`, in the header and in the refresh error alike: a frame differs only once a minute. */
+export const clockOf = (locale: string, now: Date = new Date()): string =>
+  now.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' })
 
 export const renderSnapshot = (
   snapshot: Snapshot,
@@ -29,6 +34,7 @@ export const renderSnapshot = (
   width: number,
   locale: string,
 ): Screen => {
+  setTones(snapshot.tones ?? DEFAULT_TONES)
   const screen = renderSelected(
     {
       title: snapshot.title,
@@ -38,6 +44,10 @@ export const renderSnapshot = (
       watch: snapshot.watch,
       watchesTickets: snapshot.watchesTickets,
       awaiting: snapshot.waiting,
+      groomedDays: snapshot.groomedDays,
+      next: snapshot.next,
+      appointments: snapshot.appointments,
+      sourceBlock: snapshot.sourceBlock,
       unplaced: snapshot.unplaced,
     },
     selection,
@@ -50,19 +60,23 @@ export const startSelection = (snapshot: Snapshot, options: Options): Selection
   options.lane ? laneSelection(snapshot.views[0]?.progress) : overviewSelection()
 
 /** Header and footer stay put; the body shows `bodyRows` lines from `top`, padded so the footer sits at the bottom. */
-export const draw = (screen: Screen, top: number): void => {
-  const width = paneWidth()
-  const rows = bodyRows(screen)
+export const frameOutput = (screen: Screen, top: number, width: number, rows: number): string => {
   const body = screen.body.lines.slice(top, top + rows)
   const padding = Array.from({ length: Math.max(rows - body.length, 0) }, () => '')
   const lines = [...screen.header, ...body, ...padding, ...screen.footer]
-  process.stdout.write(
-    `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`,
-  )
+  return `${CURSOR_HOME}${lines.map((line) => `${fit(line, width)}${CLEAR_LINE_END}`).join('\r\n')}${CLEAR_BELOW}`
 }
 
-/** One frame as text; ANSI styling is dropped when stdout is not a terminal. */
+/** The frame to write, or null when the terminal already shows it; a null `previous` means the terminal content is unknown. */
+export const frameToWrite = (previous: string | null, next: string): string | null => (previous === next ? null : next)
+
+const ARTIFACT_ADDRESS = new RegExp(ARTIFACT_LINK_KIND.pattern)
+
+/**
+ * One frame as text; ANSI styling is dropped when stdout is not a terminal, and links are written out as their
+ * address, except an Artifact's, which is long and would push the rest of its line past the pane.
+ */
 export const frameText = (screen: Screen, isTerminal: boolean): string => {
   const lines = [...screen.header, ...screen.body.lines, ...screen.footer]
-  return (isTerminal ? lines : lines.map(plainText)).join('\n')
+  return (isTerminal ? lines : lines.map((line) => plainText(line, (url) => !ARTIFACT_ADDRESS.test(url)))).join('\n')
 }