jackherd 0.0.1 → 1.0.1

package/src/watch/sources.ts

@@ -0,0 +1,344 @@
+import { createHash } from 'node:crypto'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { isRecord } from './json-guards'
+import { previewUrlOf } from './previews'
+import { SOURCE_FIELD } from './source-fields'
+import { ROOT_PATH, type SourcePath, selectPath } from './source-path'
+
+export const SOURCE_EVENT = 'source'
+
+export const SOURCE_CHANGE = { new: 'new', updated: 'updated' } as const
+
+export type SourceChange = (typeof SOURCE_CHANGE)[keyof typeof SOURCE_CHANGE]
+
+/** Why a run of a source failed, as a class only: never its stderr, which may carry a token. `exit <code>` comes from `exitFailure`. */
+export const SOURCE_FAILURE = {
+  timeout: 'timeout',
+  tooLarge: 'output too large',
+  unreadable: 'output unreadable',
+  notStarted: 'not started',
+  noJson: 'no JSON',
+  shape: 'unexpected shape',
+} as const
+
+/** The paths of an entry's fields: `id` and `updatedAt`, the content fields, and any further named field. */
+export type SourceMap = {
+  id: SourcePath
+  updatedAt: SourcePath
+  title?: SourcePath
+  url?: SourcePath
+  body?: SourcePath
+  author?: SourcePath
+} & Record<string, SourcePath | undefined>
+
+/**
+ * One `watch.sources` entry as the watcher uses it; `every` is in minutes, `items` the path of the list (the root
+ * without it), `reportLimit` the most entries one report shows of it.
+ */
+export type SourceSettings = {
+  name: string
+  command: readonly string[]
+  every: number
+  items?: SourcePath
+  map: SourceMap
+  ignoreAuthors: readonly string[]
+  reportLimit: number
+  lane?: string
+  /** The mapped fields whose change reports, in place of the content fingerprint; without it the fingerprint decides. */
+  reportOn?: readonly string[]
+}
+
+/**
+ * One entry of a source's output after `map`; `url` is a checked https URL or null, a missing text field is empty.
+ * `fingerprint` stands for its content (`contentFingerprint`): it changes with the text, not with the time alone.
+ */
+export type SourceItem = {
+  id: string
+  updatedAt: string
+  title: string
+  url: string | null
+  body: string
+  author: string | null
+  fingerprint: string
+  /** The `reportOn` fields as the state keeps them (`storedValue`); empty without `reportOn`. */
+  values: Record<string, string>
+}
+
+export type SourceResult = { ok: true; items: SourceItem[] } | { ok: false; reason: string }
+
+/** The outcome of one run of the source `name`. */
+export type SourceRun = { name: string; result: SourceResult }
+
+/** `[id, fingerprint]`, or with `reportOn` `[id, fingerprint, values]`: the stored value of each `reportOn` field. */
+export type SeenEntry = [string, string] | [string, string, Record<string, string>]
+
+/**
+ * What the watcher keeps per source: `seen` holds a `SeenEntry` per id, the entries seen most recently last, or null
+ * before the first successful run (which is a baseline); `failingSince` is the epoch milliseconds of the first failed
+ * run of the current streak, null while the source answers. Of an entry's text only the `reportOn` fields are kept.
+ */
+export type SourceRecord = { seen: SeenEntry[] | null; failingSince: number | null }
+
+export type SourceState = Record<string, SourceRecord>
+
+/** A `reportOn` field whose stored value changed; an empty value is `''`. */
+export type FieldChange = { field: string; from: string; to: string }
+
+export type SourceItemEvent = {
+  kind: typeof SOURCE_EVENT
+  name: string
+  lane: string | null
+  id: string
+  title: string
+  change: SourceChange
+  body: string
+  url: string | null
+  /** With `reportOn`, the fields an `updated` reports. */
+  changes?: FieldChange[]
+}
+
+export type SourceFailureEvent = { kind: typeof SOURCE_EVENT; name: string; lane: string | null; failure: string }
+
+/** The entries of one run past `reportLimit`: seen and recorded, only counted in the report. */
+export type SourceOverflowEvent = { kind: typeof SOURCE_EVENT; name: string; lane: string | null; more: number }
+
+export type SourceEvent = SourceItemEvent | SourceFailureEvent | SourceOverflowEvent
+
+const SEEN_LIMIT = 1000
+const FINGERPRINT_LENGTH = 16
+const STORED_VALUE_LENGTH = 200
+const STORED_PREFIX_LENGTH = 180
+const VALUE_HASH_LENGTH = 8
+const MINUTE_MS = 60_000
+
+export const exitFailure = (code: number): string => `exit ${code}`
+
+export const emptySourceState = (): SourceState => ({})
+
+const scalarText = (value: unknown): string | null => {
+  if (typeof value === 'string') return value
+  return typeof value === 'number' && Number.isFinite(value) ? String(value) : null
+}
+
+/** The text at `path` of an entry: a string, or a finite number as text; null for anything else or no path. */
+export const textAt = (entry: unknown, path: SourcePath | undefined): string | null =>
+  path === undefined ? null : scalarText(selectPath(entry, path))
+
+type MappedFields = Omit<SourceItem, 'fingerprint' | 'values'>
+
+const hashOf = (text: string, length: number): string =>
+  createHash('sha256').update(text).digest('hex').slice(0, length)
+
+/** A value as the state keeps it: whole up to 200 characters, else its first 180, `…` and a hash of the whole. */
+export const storedValue = (text: string): string =>
+  text.length <= STORED_VALUE_LENGTH
+    ? text
+    : `${text.slice(0, STORED_PREFIX_LENGTH)}…${hashOf(text, VALUE_HASH_LENGTH)}`
+
+const hasContentField = (map: SourceMap): boolean =>
+  [map.title, map.author, map.body, map.url].some((path) => path !== undefined)
+
+/**
+ * A short hash of what a reader sees of an entry: title, author, body and URL, so a change of the time alone (a label,
+ * a status) is no change. Without any of them mapped it is `updatedAt`, else the entry could never change.
+ */
+const contentFingerprint = (fields: MappedFields, map: SourceMap): string => {
+  const content = hasContentField(map) ? [fields.title, fields.author, fields.body, fields.url] : [fields.updatedAt]
+  return hashOf(JSON.stringify(content), FINGERPRINT_LENGTH)
+}
+
+/** A value as one line: whitespace runs one space, control characters gone, trimmed. */
+export const lineText = (text: string): string => terminalSafe(text.replace(/\s+/g, ' ')).trim()
+
+/** The value of a `reportOn` field: the checked URL for `url`, the mapped text otherwise, `''` when missing. */
+const reportedValue = (entry: unknown, field: string, fields: MappedFields, map: SourceMap): string => {
+  if (field === SOURCE_FIELD.url) return fields.url ?? ''
+  return Object.hasOwn(map, field) ? (textAt(entry, map[field]) ?? '') : ''
+}
+
+const valuesOf = (
+  entry: unknown,
+  fields: MappedFields,
+  settings: Pick<SourceSettings, 'map' | 'reportOn'>,
+): Record<string, string> =>
+  Object.fromEntries(
+    (settings.reportOn ?? []).map((field) => [
+      field,
+      storedValue(lineText(reportedValue(entry, field, fields, settings.map))),
+    ]),
+  )
+
+/** One entry after `map`, or null when its id or updatedAt is missing or no text. */
+const sourceItemOf = (entry: unknown, settings: Pick<SourceSettings, 'map' | 'reportOn'>): SourceItem | null => {
+  const { map } = settings
+  const id = textAt(entry, map.id)
+  const updatedAt = textAt(entry, map.updatedAt)
+  if (id === null || id === '' || updatedAt === null) return null
+  const url = textAt(entry, map.url)
+  const fields = {
+    id,
+    updatedAt,
+    title: textAt(entry, map.title) ?? '',
+    url: url === null ? null : previewUrlOf(url, undefined),
+    body: textAt(entry, map.body) ?? '',
+    author: textAt(entry, map.author),
+  }
+  return { ...fields, fingerprint: contentFingerprint(fields, map), values: valuesOf(entry, fields, settings) }
+}
+
+/** The items once each: an id listed twice counts with its last entry. */
+const uniqueById = (items: readonly SourceItem[]): SourceItem[] => [
+  ...new Map(items.map((item) => [item.id, item])).values(),
+]
+
+const parseJson = (text: string): { ok: true; value: unknown } | { ok: false } => {
+  try {
+    return { ok: true, value: JSON.parse(text) }
+  } catch {
+    return { ok: false }
+  }
+}
+
+/** The raw entries of a source's stdout, the list at `items`; `no JSON` or `unexpected shape` when there is none. */
+export const listAt = (
+  stdout: string,
+  items: SourcePath | undefined,
+): { ok: true; list: unknown[] } | { ok: false; reason: string } => {
+  const parsed = parseJson(stdout)
+  if (!parsed.ok) return { ok: false, reason: SOURCE_FAILURE.noJson }
+  const list = selectPath(parsed.value, items ?? ROOT_PATH)
+  return Array.isArray(list) ? { ok: true, list } : { ok: false, reason: SOURCE_FAILURE.shape }
+}
+
+/** A source's stdout read over `items` and `map`; `no JSON` or `unexpected shape` when it cannot be. */
+export const parseSourceOutput = (
+  stdout: string,
+  settings: Pick<SourceSettings, 'items' | 'map' | 'reportOn'>,
+): SourceResult => {
+  const raw = listAt(stdout, settings.items)
+  if (!raw.ok) return raw
+  const items = raw.list.map((entry) => sourceItemOf(entry, settings))
+  if (items.some((item) => item === null)) return { ok: false, reason: SOURCE_FAILURE.shape }
+  return { ok: true, items: uniqueById(items as SourceItem[]) }
+}
+
+/** Whether a source last started at `lastRunAt` (undefined: never in this process) is due again at `now`. */
+export const isSourceDue = (lastRunAt: number | undefined, everyMinutes: number, now: number): boolean =>
+  lastRunAt === undefined || now - lastRunAt >= everyMinutes * MINUTE_MS
+
+/** Whether `ignoreAuthors` holds the item back; case is ignored. */
+export const isIgnoredAuthor = (item: SourceItem, ignoreAuthors: readonly string[]): boolean =>
+  item.author !== null && ignoreAuthors.some((author) => author.toLowerCase() === item.author?.toLowerCase())
+
+type ItemChange = { change: SourceChange; changes?: FieldChange[] }
+
+/** The `reportOn` fields whose stored value differs; a field without a stored value is a baseline, not a change. */
+const fieldChanges = (stored: Record<string, string>, item: SourceItem): FieldChange[] =>
+  Object.entries(item.values).flatMap(([field, to]) => {
+    const from = Object.hasOwn(stored, field) ? stored[field] : undefined
+    return from === undefined || from === to ? [] : [{ field, from, to }]
+  })
+
+/** With `reportOn` the stored values decide (an entry stored without them is a baseline), else the fingerprint. */
+const changeOf = (
+  seen: ReadonlyMap<string, SeenEntry>,
+  item: SourceItem,
+  settings: SourceSettings,
+): ItemChange | null => {
+  const known = seen.get(item.id)
+  if (known === undefined) return { change: SOURCE_CHANGE.new }
+  if (settings.reportOn === undefined) return known[1] === item.fingerprint ? null : { change: SOURCE_CHANGE.updated }
+  const changes = known[2] === undefined ? [] : fieldChanges(known[2], item)
+  return changes.length === 0 ? null : { change: SOURCE_CHANGE.updated, changes }
+}
+
+const itemEvents = (
+  record: SourceRecord | undefined,
+  items: readonly SourceItem[],
+  settings: SourceSettings,
+): SourceEvent[] => {
+  if (!record?.seen) return []
+  const seen = new Map(record.seen.map((entry) => [entry[0], entry]))
+  const lane = settings.lane ?? null
+  const events = items.flatMap((item): SourceItemEvent[] => {
+    const found = changeOf(seen, item, settings)
+    if (found === null || isIgnoredAuthor(item, settings.ignoreAuthors)) return []
+    const { id, title, body, url } = item
+    return [{ kind: SOURCE_EVENT, name: settings.name, lane, id, title, body, url, ...found }]
+  })
+  const more = events.length - settings.reportLimit
+  if (more <= 0) return events
+  return [...events.slice(0, settings.reportLimit), { kind: SOURCE_EVENT, name: settings.name, lane, more }]
+}
+
+/**
+ * The events of `runs` against `previous`: per item `new` for an unknown id, `updated` for a changed fingerprint (with
+ * `reportOn`: a changed stored value of a listed field, named in `changes`), none
+ * for an author in `ignoreAuthors`, at most `reportLimit` per source and the rest counted in one event; a source's
+ * first successful run is a baseline. A failure fires once per streak.
+ */
+export const sourceEvents = (
+  previous: SourceState,
+  runs: readonly SourceRun[],
+  settings: readonly SourceSettings[],
+): SourceEvent[] =>
+  runs.flatMap(({ name, result }): SourceEvent[] => {
+    const source = settings.find((candidate) => candidate.name === name)
+    if (!source) return []
+    const record = previous[name]
+    if (result.ok) return itemEvents(record, result.items, source)
+    const known = record?.failingSince != null
+    return known ? [] : [{ kind: SOURCE_EVENT, name, lane: source.lane ?? null, failure: result.reason }]
+  })
+
+/** `[id, fingerprint]`, with the `reportOn` values as a third part when there are any. */
+const seenEntryOf = ({ id, fingerprint, values }: SourceItem): SeenEntry =>
+  Object.keys(values).length === 0 ? [id, fingerprint] : [id, fingerprint, values]
+
+/** The seen entries with `items` moved to the end, the most recent `SEEN_LIMIT` kept. */
+const seenAfter = (seen: readonly SeenEntry[], items: readonly SourceItem[]): SeenEntry[] => {
+  const current = new Set(items.map(({ id }) => id))
+  const kept = seen.filter(([id]) => !current.has(id))
+  return [...kept, ...items.map(seenEntryOf)].slice(-SEEN_LIMIT)
+}
+
+const recordOf = (record: SourceRecord | undefined, result: SourceResult, now: number): SourceRecord =>
+  result.ok
+    ? { seen: seenAfter(record?.seen ?? [], result.items), failingSince: null }
+    : { seen: record?.seen ?? null, failingSince: record?.failingSince ?? now }
+
+/**
+ * The state after `runs` for the sources configured as `names`: a run records its outcome, a source without a run keeps
+ * its record, a source no longer configured is dropped. Recording the same runs twice gives the same state.
+ */
+export const recordSources = (
+  previous: SourceState,
+  runs: readonly SourceRun[],
+  names: readonly string[],
+  now: number,
+): SourceState =>
+  Object.fromEntries(
+    names.flatMap((name) => {
+      const run = runs.find((candidate) => candidate.name === name)
+      const record = run ? recordOf(previous[name], run.result, now) : previous[name]
+      return record ? [[name, record]] : []
+    }),
+  )
+
+const isStoredValues = (value: unknown): boolean =>
+  isRecord(value) && Object.values(value).every((part) => typeof part === 'string')
+
+const isSeenEntry = (value: unknown): boolean =>
+  Array.isArray(value) &&
+  (value.length === 2 || value.length === 3) &&
+  typeof value[0] === 'string' &&
+  typeof value[1] === 'string' &&
+  (value.length === 2 || isStoredValues(value[2]))
+
+const isSourceRecord = (value: unknown): boolean =>
+  isRecord(value) &&
+  (value.seen === null || (Array.isArray(value.seen) && value.seen.every(isSeenEntry))) &&
+  (value.failingSince === null || typeof value.failingSince === 'number')
+
+export const isSourceState = (value: unknown): value is SourceState =>
+  isRecord(value) && Object.values(value).every(isSourceRecord)

package/src/watch/stream-output.ts

@@ -0,0 +1,14 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { type LaneSnapshot, NO_AGENT } from './lane-watch'
+import { WATCH_EVENT } from './watch-events'
+
+/**
+ * The heartbeat of a stream, as one line, since every line of a stream reaches the coordinator as a
+ * message of its own: `=== heartbeat <time> · <lane> <status> · …`.
+ */
+export const streamHeartbeatLine = (time: string, lanes: readonly string[], current: LaneSnapshot): string => {
+  const states = lanes.map((lane) => `${terminalSafe(lane)} ${terminalSafe(current[lane]?.status ?? NO_AGENT)}`)
+  return [`=== ${WATCH_EVENT.heartbeat} ${terminalSafe(time)}`, ...(states.length > 0 ? states : ['no lanes'])].join(
+    ' · ',
+  )
+}

package/src/watch/texts.ts

@@ -0,0 +1,76 @@
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+
+/** The words of the watcher's status and duty lines, in the project's response language. */
+export type WatchTexts = {
+  noBranch: string
+  noPullRequest: string
+  openPhase: string
+  /** The current phase ticked to the end in the lane's worktree, its ticks not yet on the base branch. */
+  tickedUnmerged: string
+  phase: string
+  startsAfter: string
+  planFinished: string
+  noPlan: string
+  noName: string
+  noValue: string
+  unnamedPane: (name: string) => string
+  noAgentNamed: (name: string) => string
+  /** The prefix of a merge's duty line, with the pull request number. */
+  afterMerge: (number: number) => string
+  mergedLaneDuty: string
+  otherLaneDuty: string
+  blockedDuty: string
+  /** What a lane whose context reached `alert` asks of the coordinator. */
+  laneAlertDuty: string
+  /** The reminder after the coordinator line: `<term>: <count> rows only in the checkout`. */
+  checkoutRows: (term: string, count: number) => string
+  /** The head of the status line of the user's own open pull requests without a lane. */
+  otherPullRequests: string
+}
+
+export const WATCH_TEXTS: Record<PlanLanguage, WatchTexts> = {
+  [PLAN_LANGUAGE.de]: {
+    noBranch: 'kein Branch',
+    noPullRequest: 'kein PR',
+    openPhase: 'offene Phase',
+    tickedUnmerged: 'abgehakt, nicht gemergt',
+    phase: 'Phase',
+    startsAfter: 'Startet nach',
+    planFinished: 'Plan fertig',
+    noPlan: 'kein Plan',
+    noName: 'kein Name',
+    noValue: 'kein Wert',
+    unnamedPane: (name) => `Pane ohne Namen, herdr agent rename "$HERDR_PANE_ID" ${name}`,
+    noAgentNamed: (name) => `kein Agent namens ${name}`,
+    afterMerge: (number) => `nach Merge #${number}`,
+    mergedLaneDuty: 'nächste Phase starten oder Spur schließen',
+    otherLaneDuty: 'rebasen, dann nächste Phase starten oder Grund nennen',
+    blockedDuty:
+      'Frage gegen Plan und Regeln prüfen, in der Spur beantworten oder per Dialog an den User; nie das Pane weiterreichen',
+    laneAlertDuty: 'Übergabe an der nächsten Phasengrenze anfordern (§ 8)',
+    checkoutRows: (term, count) => `${term}: ${count} ${count === 1 ? 'Zeile' : 'Zeilen'} nur im Checkout`,
+    otherPullRequests: 'andere PRs',
+  },
+  [PLAN_LANGUAGE.en]: {
+    noBranch: 'no branch',
+    noPullRequest: 'no PR',
+    openPhase: 'open phase',
+    tickedUnmerged: 'ticked, not merged',
+    phase: 'phase',
+    startsAfter: 'starts after',
+    planFinished: 'plan finished',
+    noPlan: 'no plan',
+    noName: 'no name',
+    noValue: 'no value',
+    unnamedPane: (name) => `pane without a name, herdr agent rename "$HERDR_PANE_ID" ${name}`,
+    noAgentNamed: (name) => `no agent named ${name}`,
+    afterMerge: (number) => `after merge #${number}`,
+    mergedLaneDuty: 'start the next phase or close the lane',
+    otherLaneDuty: 'rebase, then start the next phase or name the reason to wait',
+    blockedDuty:
+      'vet the question against the plan and the rules, answer it in the lane or ask the user in a dialog; never hand the pane over',
+    laneAlertDuty: 'request the hand-over at the next phase boundary (§ 8)',
+    checkoutRows: (term, count) => `${term}: ${count} ${count === 1 ? 'row' : 'rows'} only in the checkout`,
+    otherPullRequests: 'other PRs',
+  },
+}