jackherd 1.8.0 → 1.9.0

package/src/plans/phase-ranges.ts

@@ -0,0 +1,45 @@
+import { phaseLabel } from '../plan-format'
+
+const RANGE_DASH = '–'
+const RANGE_SEPARATOR = ', '
+/** A phase id as a number with an optional sub-phase letter: `10`, `10c`. */
+const NUMBERED_ID = /^(\d+)([a-z]*)$/i
+
+/** One entry of the text: a run of whole phases `first`–`last`, or one id that stands alone. */
+type Entry = { first: number; last: number } | { alone: string }
+
+const byNumber = (first: string, second: string): number => first.localeCompare(second, undefined, { numeric: true })
+
+const entryText = (entry: Entry): string => {
+  if ('alone' in entry) return phaseLabel(entry.alone)
+  const first = phaseLabel(String(entry.first))
+  return entry.first === entry.last ? first : `${first}${RANGE_DASH}${phaseLabel(String(entry.last))}`
+}
+
+/** The entry `id` extends, or the entries with `id` after them; `wholes` are the main phases among the ids. */
+const withId = (entries: Entry[], id: string, wholes: ReadonlySet<string>): Entry[] => {
+  const [, main = '', sub = ''] = NUMBERED_ID.exec(id) ?? []
+  if (main === '' || (sub !== '' && !wholes.has(String(Number(main))))) return [...entries, { alone: id }]
+  if (sub !== '') return entries
+  const number = Number(main)
+  const last = entries.at(-1)
+  if (last && !('alone' in last) && last.last === number - 1)
+    return [...entries.slice(0, -1), { ...last, last: number }]
+  return [...entries, { first: number, last: number }]
+}
+
+/**
+ * Phase ids as ranges, numbered ids by number first: `P1–P7, P10–P15`. A gap ends a range; a sub-phase (`P10c`) is
+ * inside its main phase when that one is among the ids too, else it stands alone between the ranges. An id that is
+ * no number stands alone after the numbered ones. Empty for no id.
+ */
+export const phaseRanges = (ids: readonly string[]): string => {
+  const sorted = [...new Set(ids)].sort(byNumber)
+  const numbered = sorted.filter((id) => NUMBERED_ID.test(id))
+  const wholes = new Set(numbered.filter((id) => /^\d+$/.test(id)).map((id) => String(Number(id))))
+  const others = sorted.filter((id) => !NUMBERED_ID.test(id))
+  return [...numbered, ...others]
+    .reduce<Entry[]>((entries, id) => withId(entries, id, wholes), [])
+    .map(entryText)
+    .join(RANGE_SEPARATOR)
+}

package/src/plans/pull-requests.ts

@@ -176,6 +176,12 @@ export const pullRequestsByBranch = (pullRequests: readonly PullRequest[]): Map<
 /** The selection key of a pull request row; two parts, so it never equals a three-part phase key. */
 export const pullRequestKey = (number: number): string => `pr:${number}`
 
+/**
+ * The key of a failed test's line under a pull request, by its place in the list: a click unfolds a cut name and folds
+ * it again. No colon and no `#`, so it never reads as a phase or task key.
+ */
+export const failedTestKey = (number: number, index: number): string => `failed>${number}>${index}`
+
 /** The link behind a row key, or null when the key is a phase or a pull request no longer open. */
 export const pullRequestUrl = (pullRequests: readonly PullRequest[], key: string): string | null =>
   pullRequests.find((pullRequest) => pullRequestKey(pullRequest.number) === key)?.url ?? null

package/src/plans/selection.ts

@@ -3,11 +3,10 @@ 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.
+ * Whether a lane is drawn open. It is decided once, when the lane first appears (`autoOpen`, by its status then), and
+ * changes only when a person opens or closes it: a change of status moves neither this nor the order of the lanes.
  */
-export type LaneFold = { status: string | null; open: boolean }
+export type LaneFold = { open: boolean }
 
 /**
  * The row under the cursor and the expanded phases, both as keys, whether ticked phases and items are
@@ -61,7 +60,7 @@ 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
+export 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) ?? []
@@ -102,22 +101,19 @@ const laneOfKey = (key: string): string | null => (key.startsWith(LANE_KEY_PREFI
 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)
-}
+/** Whether a lane is drawn open: its fold, else, for a lane that has none yet, the automatic rule for its status. */
+export const isLaneOpen = ({ laneFolds }: Selection, lane: string, status: string | null): boolean =>
+  laneFolds.get(lane)?.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.
+ * Lets the folds follow the lanes: a lane keeps its fold whatever its status does, gets the automatic one only when
+ * 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) })
+    folds.set(lane, fold ?? { open: autoOpen(status) })
   }
   const unchanged =
     folds.size === selection.laneFolds.size &&
@@ -134,10 +130,10 @@ export const overviewSelection = (): Selection => ({
 })
 
 /** 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 => {
+export const laneSelection = (progress: LaneProgress | undefined): Selection => {
   const base = overviewSelection()
   if (!progress) return base
-  const opened = { ...base, laneFolds: new Map([[progress.lane.name, { status, open: true }]]) }
+  const opened = { ...base, laneFolds: new Map([[progress.lane.name, { open: true }]]) }
   const phase = currentPhase(progress)
   if (!progress.current || !phase) return opened
   const key = phaseKey(progress.lane.name, progress.current.stepIndex, phase.id)
@@ -215,6 +211,13 @@ const changeSelected = (selection: Selection, keys: readonly string[], next: (op
   return { ...selection, selected: current, expanded }
 }
 
+/** The selection with `key` expanded when it was folded and folded when it was expanded; nothing else changes. */
+export const toggledExpansion = (selection: Selection, key: string): Selection => {
+  const expanded = new Set(selection.expanded)
+  if (!expanded.delete(key)) expanded.add(key)
+  return { ...selection, 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)

package/src/plans/sent-files-read.ts

@@ -0,0 +1,22 @@
+import { join } from 'node:path'
+import { readRecords, writeRecordAtomically } from '../shared/private-records'
+import { isSentFileRecord, type SentFileRecord } from './sent-files'
+
+const directoryOf = (root: string): string => join(root, '.jackherd', 'sent')
+
+/** Every record of the sent-file log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
+export const readSentRecords = (root: string): SentFileRecord[] =>
+  readRecords(directoryOf(root), isSentFileRecord, ({ sentAt }) => sentAt)
+
+const closeWhere = (root: string, isChosen: (record: SentFileRecord) => boolean, now: number): number => {
+  const open = readSentRecords(root).filter((record) => record.closedAt === null && isChosen(record))
+  for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
+  return open.length
+}
+
+/** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+export const closeSentRecords = (root: string, ids: readonly string[], now: number): number =>
+  closeWhere(root, (record) => ids.includes(record.id), now)
+
+/** Marks every open record `closedAt` and returns how many it closed. */
+export const closeAllSentRecords = (root: string, now: number): number => closeWhere(root, () => true, now)

package/src/plans/sent-files.ts

@@ -0,0 +1,121 @@
+import { basename } from 'node:path'
+import { twoDigits } from '../plan-format/clock'
+import { terminalSafe } from '../plan-format/terminal-text'
+import type { WaitingItem } from '../plan-format/waiting'
+import { laneDirectoryOf } from './unlisted-lanes'
+
+/** The record of a send of files to the user, as the kit hook `sent-file` writes it to `.jackherd/sent/`. */
+export type SentFileRecord = {
+  id: string
+  files: string[]
+  caption: string | null
+  sentAt: number
+  cwd: string
+  session: string
+  agentId: string | null
+  closedAt: number | null
+}
+
+/** A badge for a sent file: a `file:` address and the file's name. */
+export type SentChip = { url: string; label: string }
+
+const ID = /^[0-9a-f]{12}$/
+/** The address of a published artifact, as the hook reads it from the tool's answer, as a whole. */
+const ARTIFACT_ADDRESS = /^https:\/\/claude\.ai\/(?:code\/)?artifact\/[A-Za-z0-9_-]+$/
+const DAY_MS = 86_400_000
+/** A send waits on the user this long at most; the coordinator closes it earlier, with the answer. */
+const WAITING_DAYS = 3
+const SHOWN_PER_LANE = 5
+
+/** A published artifact is recorded by its address; a sent file by its path. */
+const isAddress = (file: string): boolean => file.startsWith('https://')
+
+const addressOf = (file: string): string =>
+  isAddress(file) ? file : `file://${file.split('/').map(encodeURIComponent).join('/')}`
+
+/** What a badge or a for-you row shows of a file, without the control characters a hand-written record may carry. */
+const labelOf = (file: string, caption: string | null): string =>
+  terminalSafe(isAddress(file) ? (caption ?? 'artifact') : basename(file))
+
+/** A file entry: an artifact address as a whole, else a path; an https entry of another shape is refused. */
+const isRecordedFile = (file: string): boolean => !isAddress(file) || ARTIFACT_ADDRESS.test(file)
+
+const isStringArray = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === 'string')
+
+/** The same shape as `isSentRecord` in the hook, which this package does not import at run time (contract test). */
+export const isSentFileRecord = (value: unknown): value is SentFileRecord => {
+  if (typeof value !== 'object' || value === null) return false
+  const record = value as Record<string, unknown>
+  return (
+    typeof record.id === 'string' &&
+    ID.test(record.id) &&
+    isStringArray(record.files) &&
+    record.files.every(isRecordedFile) &&
+    (record.caption === null || typeof record.caption === 'string') &&
+    typeof record.sentAt === 'number' &&
+    typeof record.cwd === 'string' &&
+    typeof record.session === 'string' &&
+    (record.agentId === null || typeof record.agentId === 'string') &&
+    (record.closedAt === null || typeof record.closedAt === 'number')
+  )
+}
+
+/**
+ * The lane a send belongs to: the worktree of the first file below `worktreeDirectory`, else the worktree of the
+ * directory it was sent from; null for the coordinator.
+ */
+export const sentLaneOf = ({ files, cwd }: SentFileRecord, worktreeDirectory: string): string | null =>
+  files
+    .map((file) => (isAddress(file) ? null : laneDirectoryOf(file, worktreeDirectory)))
+    .find((lane) => lane !== null) ?? laneDirectoryOf(cwd, worktreeDirectory)
+
+/** The records without an earlier send of the same first file: an artifact updated each round is one send, the newest. */
+const latestPerFile = (records: readonly SentFileRecord[]): SentFileRecord[] =>
+  records.filter((record, index) => !records.slice(index + 1).some((later) => later.files[0] === record.files[0]))
+
+/**
+ * The badges of the files sent within the last day, by lane (null: the coordinator's), newest first and at most five
+ * per lane. A closed send still shows its files: the badge is the way back to them.
+ */
+export const sentChipsByLane = (
+  records: readonly SentFileRecord[],
+  worktreeDirectory: string,
+  now: number,
+): Map<string | null, SentChip[]> => {
+  const lanes = new Map<string | null, SentChip[]>()
+  const recent = latestPerFile([...records].sort((left, right) => left.sentAt - right.sentAt))
+    .filter(({ sentAt }) => now - sentAt <= DAY_MS)
+    .sort((left, right) => right.sentAt - left.sentAt)
+  for (const record of recent) {
+    const lane = sentLaneOf(record, worktreeDirectory)
+    const chips = lanes.get(lane) ?? []
+    for (const file of record.files) chips.push({ url: addressOf(file), label: labelOf(file, record.caption) })
+    lanes.set(lane, chips.slice(0, SHOWN_PER_LANE))
+  }
+  return lanes
+}
+
+const clockText = (at: number): string => {
+  const date = new Date(at)
+  return `${twoDigits(date.getDate())}.${twoDigits(date.getMonth() + 1)}. ${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
+}
+
+const itemOf = (record: SentFileRecord): WaitingItem => {
+  const [first] = record.files
+  const more = record.files.length > 1 ? ` +${record.files.length - 1}` : ''
+  return {
+    since: clockText(record.sentAt),
+    item: `${labelOf(first, record.caption)}${more}`,
+    kind: 'file',
+    id: record.id,
+    open: true,
+    url: addressOf(first),
+  }
+}
+
+/** What the sends that no one closed wait on: one open item per record younger than three days, oldest first. */
+export const sentWaitingItems = (records: readonly SentFileRecord[], now: number): WaitingItem[] =>
+  latestPerFile(records)
+    .filter(({ closedAt, sentAt }) => closedAt === null && now - sentAt <= WAITING_DAYS * DAY_MS)
+    .map(itemOf)

package/src/plans/signals-read.ts

@@ -0,0 +1,54 @@
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { projectDirectoryOf } from '../context/session-log'
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { readClaudeSignals } from '../task-signals/claude-read'
+import { recordSignals } from '../task-signals/record'
+import { readTaskRecords } from '../task-signals/record-store'
+import type { TaskSignal } from '../task-signals/types'
+import { STALE_ACTIVITY_MINUTES } from './lane-summary'
+
+export type SignalSource = {
+  /** Claude Code's `projects` directory. */
+  projects: string
+  /** The main checkout, where the coordinator works and `.jackherd/tasks/` lives. */
+  root: string
+  /** The directory the lanes' worktrees lie in. */
+  worktrees: string
+}
+
+const subdirectories = (path: string): string[] => {
+  try {
+    return readdirSync(path, { withFileTypes: true }).flatMap((entry) =>
+      entry.isDirectory() ? [join(path, entry.name)] : [],
+    )
+  } catch {
+    return []
+  }
+}
+
+const recentSessionLogs = (project: string, notOlderThan: number): string[] => {
+  try {
+    return readdirSync(project)
+      .filter((name) => name.endsWith('.jsonl'))
+      .map((name) => join(project, name))
+      .filter((path) => statSync(path).mtimeMs >= notOlderThan)
+  } catch {
+    return []
+  }
+}
+
+/**
+ * What agents report doing, as `TaskSignal`s: the tasks in progress in the recent Claude Code sessions of the main
+ * checkout (the coordinator and its subagents) and of every worktree, and the open `jh task` records. Which lane a
+ * signal belongs to is decided by its `cwd`, not by where it was read.
+ */
+export const readAllSignals = ({ projects, root, worktrees }: SignalSource, now: number): TaskSignal[] => {
+  const notOlderThan = now - STALE_ACTIVITY_MINUTES * MS_PER_MINUTE
+  const claude = [root, ...subdirectories(worktrees)].flatMap((directory) =>
+    recentSessionLogs(join(projects, projectDirectoryOf(directory)), notOlderThan).flatMap((path) =>
+      readClaudeSignals(path, { notOlderThan }),
+    ),
+  )
+  return [...claude, ...recordSignals(readTaskRecords(root))]
+}