jackherd 1.12.1 → 1.12.3

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/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/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)