jackherd 1.12.2 → 1.12.4

package/src/watch/herd-publisher.ts

@@ -0,0 +1,84 @@
+import { rmSync } from 'node:fs'
+import { TERMINAL_ADAPTER } from '../config/schema'
+import { errorText } from '../plans/error-text'
+import {
+  type HerdRead,
+  herdFilesOf,
+  publishDecision,
+  publishedKey,
+  storedRead,
+  type Written,
+  writeHerdFile,
+} from '../plans/herd-state'
+import { initialPageState, syncSprintPage } from '../plans/page-sync'
+import { startReader } from '../plans/reader'
+import type { PlansSettings } from '../plans/settings'
+import type { Snapshot, Source } from '../plans/snapshot'
+import { laneStatusSourceFor } from '../terminal'
+import { listHerdrAgents } from '../terminal/herdr'
+import type { StartedKit } from '../version/started-kit'
+
+/** What the publisher reads for: the watcher's checkout, board and settings. */
+export type PublishedBoard = { root: string; sprintFile: string; settings: PlansSettings }
+
+/** The board read as a herd without a lane reads it, with the terminal's agents read without holding the event loop. */
+const sourceOf = ({ root, sprintFile, settings }: PublishedBoard): Source => ({
+  root,
+  sprintFile,
+  options: { boardPath: null, lane: null, once: false, ensure: false },
+  settings,
+  terminal: laneStatusSourceFor(settings.adapter),
+  ...(settings.adapter === TERMINAL_ADAPTER.herdr ? { listAgents: () => listHerdrAgents() } : {}),
+})
+
+/**
+ * Reads the board once for every herd of it and publishes the read (`herd-state.ts`): the read file only when its
+ * content changed, the plan texts only when they did, and the beat after every read that worked, so a herd reads for
+ * itself again once the watcher stops or fails for longer than `PUBLISHED_MAX_AGE_MS`. It writes the sprint page as
+ * well, so no herd builds it. Returns the stop.
+ */
+export const startHerdPublisher = (board: PublishedBoard, kit: StartedKit): (() => void) => {
+  const source = sourceOf(board)
+  const key = publishedKey(board, kit)
+  const files = herdFilesOf(board.root)
+  const pageState = initialPageState()
+  const written: Written = { content: null, plansKey: null }
+  let last: { snapshot: Snapshot; fetchLine: string | null } | null = null
+  let stopped = false
+
+  /** Writes what changed and the beat; a failed write writes no beat, so the herds read for themselves soon. */
+  const publish = (): boolean => {
+    if (stopped || !last) return false
+    const { snapshot, fetchLine } = last
+    const stored: HerdRead = storedRead({ snapshot, page: pageState.page, fetchLine }, key, Date.now())
+    const { writePlans, writeRead, content } = publishDecision(written, stored)
+    try {
+      if (writePlans) writeHerdFile(files.plans, { plansKey: stored.plansKey, plans: snapshot.documents.plans })
+      written.plansKey = stored.plansKey
+      if (writeRead) writeHerdFile(files.read, stored)
+      written.content = content
+      writeHerdFile(files.beat, { key, at: stored.at })
+    } catch (error) {
+      console.log(`herd read not published: ${errorText(error)}`)
+      return false
+    }
+    return writeRead
+  }
+
+  // A beat of an earlier watcher must not vouch for its read until this one has read.
+  rmSync(files.beat, { force: true })
+  const reader = startReader(source, (outcome) => {
+    if ('error' in outcome) return false
+    last = { snapshot: outcome.read, fetchLine: reader.fetchLine() }
+    const changed = publish()
+    const { snapshot } = last
+    setTimeout(async () => {
+      if (await syncSprintPage(pageState, source, snapshot, async () => snapshot)) publish()
+    }, 0)
+    return changed
+  })
+  return () => {
+    stopped = true
+    reader.stop()
+  }
+}

package/src/watch/lane-report.ts

@@ -25,7 +25,7 @@ import {
   WATCH_EVENT,
   type WatchEvent,
 } from './watch-events'
-import type { TakeOver } from './watcher-lock'
+import { NO_TAKE_OVER, type TakeOver } from './watcher-lock'
 
 export type LaneReport = {
   lane: string
@@ -363,3 +363,19 @@ export const armLine = (lanes: readonly string[], armed: LaneSnapshot, takeOver:
     'no lanes'
   return `armed: ${states}${takeOverNote(takeOver)} board ${terminalSafe(board)}`
 }
+
+/**
+ * The `armed:` line a start prints, null when it would repeat the last start's (`previous`), and the line to remember:
+ * the one without a take-over note, so a start that replaced a watcher speaks and the one after it compares as usual.
+ */
+export const armNotice = (
+  previous: string | null,
+  lanes: readonly string[],
+  armed: LaneSnapshot,
+  takeOver: TakeOver,
+  board: string,
+): { line: string | null; state: string } => {
+  const state = armLine(lanes, armed, NO_TAKE_OVER, board)
+  const line = armLine(lanes, armed, takeOver, board)
+  return { line: line === previous ? null : line, state }
+}

package/src/watch/source-entries.ts

@@ -16,6 +16,12 @@ export const ENTRY_LIMIT = 20
 
 const shownAt = ({ changedAt, seenAt }: SourceEntry): number => changedAt ?? seenAt
 
+/** The source's own time of an entry in epoch milliseconds; null for an unmapped `updatedAt` (`''`) or no date. */
+const sourceTimeOf = (updatedAt: string): number | null => {
+  const time = updatedAt === '' ? Number.NaN : Date.parse(updatedAt)
+  return Number.isNaN(time) ? null : time
+}
+
 const entryOf = (
   item: SourceItem,
   known: SourceEntry | undefined,
@@ -29,6 +35,7 @@ const entryOf = (
   count: item.count,
   seenAt: known?.seenAt ?? now,
   changedAt: seen && reportsItem(seen, item, settings) ? now : (known?.changedAt ?? null),
+  updatedAt: sourceTimeOf(item.updatedAt),
 })
 
 /**

package/src/watch/source-statuses.ts

@@ -6,7 +6,7 @@ import type { WatchState } from './watch-events'
 /** The newest entry a source reported, as the herd draws it; `isNew` while it is younger than `NEW_FOR_MS`. */
 export type LatestStatus = { title: string; url: string | null; isNew: boolean }
 
-/** An entry as the herd lists it under its source: `at` is when it last changed, else when the watcher first saw it; `isNew` only for a reported change younger than `NEW_FOR_MS`. */
+/** An entry as the herd lists it under its source: `at` is the source's own time of it, else when it last changed, else when the watcher first saw it; `isNew` only for a reported change younger than `NEW_FOR_MS`. */
 export type EntryStatus = {
   id: string
   title: string
@@ -30,7 +30,7 @@ const entryStatusOf = (entry: SourceEntry, now: number): EntryStatus => ({
   title: lineText(entry.title),
   url: entry.url === null ? null : previewUrlOf(entry.url, undefined),
   count: entry.count,
-  at: entry.changedAt ?? entry.seenAt,
+  at: entry.updatedAt ?? entry.changedAt ?? entry.seenAt,
   isNew: entry.changedAt !== null && now - entry.changedAt < NEW_FOR_MS,
 })
 

package/src/watch/sources.ts

@@ -93,7 +93,8 @@ export type LatestReport = { title: string; url: string | null; at: number }
 
 /**
  * An entry of a source as the herd lists it: its title as one line, its checked URL, its count, when the watcher first
- * saw it (`seenAt`) and when it last reported a change of it (`changedAt`, null while only the baseline knows it).
+ * saw it (`seenAt`), when it last reported a change of it (`changedAt`, null while only the baseline knows it), and the
+ * source's own time of it (`map.updatedAt` read as a date; null when unmapped or no date, absent in older states).
  */
 export type SourceEntry = {
   id: string
@@ -102,6 +103,7 @@ export type SourceEntry = {
   count: string | null
   seenAt: number
   changedAt: number | null
+  updatedAt?: number | null
 }
 
 /**
@@ -419,7 +421,8 @@ const isSourceEntry = (value: unknown): boolean =>
   isTextOrNull(value.url) &&
   isTextOrNull(value.count) &&
   typeof value.seenAt === 'number' &&
-  (value.changedAt === null || typeof value.changedAt === 'number')
+  (value.changedAt === null || typeof value.changedAt === 'number') &&
+  (value.updatedAt === undefined || value.updatedAt === null || typeof value.updatedAt === 'number')
 
 const isSourceRecord = (value: unknown): boolean =>
   isRecord(value) &&

package/src/watch/stream-output.ts

@@ -35,3 +35,9 @@ export const streamHeartbeatLine = (
     ...standing.map((line) => terminalSafe(line).replaceAll(SEPARATOR, ' / ')),
   ].join(SEPARATOR)
 }
+
+/** A heartbeat line without its head and time: what two heartbeats are compared by. */
+export const heartbeatStateOf = (line: string): string => line.slice(line.indexOf(SEPARATOR) + SEPARATOR.length)
+
+/** Whether a heartbeat brings news against the state of the last one sent (`heartbeatStateOf`); the first one always does. */
+export const isHeartbeatNews = (previous: string | null, line: string): boolean => previous !== heartbeatStateOf(line)

package/src/watch/watch-events.ts

@@ -128,6 +128,10 @@ export type WatchState = {
   reportQuestions: Record<string, string>
   /** The lane lines of the status block last printed; null before the first report. */
   statusLines: string[] | null
+  /** The state of the last heartbeat a stream sent (`heartbeatStateOf`); null before the first one. */
+  heartbeat: string | null
+  /** The `armed:` line of the last start; a start that would print the same line stays silent. Null before the first. */
+  armed: string | null
   /** The board's appointments reported as due and its unreadable appointment rows reported, each once (`appointments.ts`). */
   appointments: AppointmentState
 }
@@ -219,6 +223,8 @@ export const emptyWatchState = (): WatchState => ({
   reportMtimes: {},
   reportQuestions: {},
   statusLines: null,
+  heartbeat: null,
+  armed: null,
   appointments: emptyAppointmentState(),
 })
 
@@ -271,6 +277,8 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   everyValue(value.reportQuestions, (entry) => typeof entry === 'string') &&
   (value.statusLines === null ||
     (Array.isArray(value.statusLines) && value.statusLines.every((line) => typeof line === 'string'))) &&
+  (value.heartbeat === null || typeof value.heartbeat === 'string') &&
+  (value.armed === null || typeof value.armed === 'string') &&
   isAppointmentState(value.appointments)
 
 /**

package/src/watch/watcher-lock.ts

@@ -18,6 +18,9 @@ export type CommandLineOf = (pid: number) => string | null
 /** What taking the lock did to a watcher that held it: stopped it, or found it still running after the wait. */
 export type TakeOver = { replaced: number | null; stillRunning: number | null }
 
+/** A start that found no watcher to take over from. */
+export const NO_TAKE_OVER: TakeOver = { replaced: null, stillRunning: null }
+
 /** The CLI's entry by source path or bin link (`jh`, and `jackherd` for `bunx jackherd`); `agent-kit` until 2.0.0, so a watcher of the old CLI is replaced. */
 const CLI_ENTRIES = ['cli.ts', CLI_NAME, PACKAGE_NAME, 'agent-kit']
 const WATCH_COMMAND = 'watch'
@@ -165,11 +168,11 @@ export const isWatcherRunning = (lockFile: string, lookUp: CommandLineOf = reade
 export const takeOverLock = async (lockFile: string): Promise<TakeOver> => {
   const previous = supersedeTarget(readPrivateText(lockFile), process.pid, commandLineOf)
   writePrivateFile(lockFile, String(process.pid))
-  if (previous === null || !isAlive(previous)) return { replaced: null, stillRunning: null }
+  if (previous === null || !isAlive(previous)) return NO_TAKE_OVER
   try {
     process.kill(previous, 'SIGTERM')
   } catch {
-    return { replaced: null, stillRunning: null }
+    return NO_TAKE_OVER
   }
   const deadline = Date.now() + STOP_WAIT_MS
   while (isAlive(previous) && Date.now() < deadline) await Bun.sleep(STOP_POLL_MS)

package/src/plans/next-rows.ts

@@ -1,12 +0,0 @@
-import { sectionLines } from '../plan-format/markdown'
-import { NEXT_VOCABULARY, type PlanLanguage } from '../vocabulary'
-
-const MAX_NEXT_LINES = 3
-
-const LIST_LINE = /^(?:\d+[.)]|[-*])\s+(.+)$/
-
-/** The board's next section, up to three list lines in the order written; the parser cuts after three, as the board says. */
-export const nextLines = (board: string, language: PlanLanguage): string[] =>
-  sectionLines(board, NEXT_VOCABULARY[language].heading)
-    .flatMap((line) => LIST_LINE.exec(line.trim())?.[1] ?? [])
-    .slice(0, MAX_NEXT_LINES)