jackherd 1.15.0 → 1.15.2

package/schemas/sources.schema.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "sources": {
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9][\\w.-]*$"
+          },
+          "command": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "every": {
+            "default": 5,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "items": {
+            "type": "string"
+          },
+          "map": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "updatedAt": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              },
+              "body": {
+                "type": "string"
+              },
+              "author": {
+                "type": "string"
+              },
+              "status": {
+                "type": "string"
+              },
+              "count": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ],
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "ignoreAuthors": {
+            "default": [],
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "reportLimit": {
+            "default": 5,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40,
+            "pattern": "^[^\\r\\n]+$"
+          },
+          "lane": {
+            "type": "string",
+            "minLength": 1
+          },
+          "ticket": {
+            "type": "boolean"
+          },
+          "tone": {
+            "type": "string",
+            "enum": [
+              "amber",
+              "teal",
+              "grey",
+              "red",
+              "green",
+              "blue",
+              "magenta"
+            ]
+          },
+          "reportOn": {
+            "minItems": 1,
+            "maxItems": 10,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "secrets": {
+            "maxItems": 10,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[A-Z][A-Z0-9_]*$"
+            }
+          },
+          "show": {
+            "type": "string",
+            "const": "entries"
+          }
+        },
+        "required": [
+          "name",
+          "command",
+          "map"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/cli.ts

@@ -28,6 +28,7 @@ export const COMMANDS: CommandTable = {
   mermaid: () => import('./mermaid/command'),
   plan: () => import('./plan-contract/command'),
   preview: () => import('./preview/command'),
+  secret: () => import('./secrets/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),
   task: () => import('./task-signals/command'),

package/src/config/json-schema.ts

@@ -1,5 +1,9 @@
 import { z } from 'zod'
-import { jackherdConfigSchema } from './schema'
+import { jackherdConfigSchema, personalSourcesSchema } from './schema'
 
-export const renderConfigJsonSchema = (): string =>
-  `${JSON.stringify(z.toJSONSchema(jackherdConfigSchema, { io: 'input' }), null, 2)}\n`
+const renderJsonSchema = (schema: z.ZodType): string =>
+  `${JSON.stringify(z.toJSONSchema(schema, { io: 'input' }), null, 2)}\n`
+
+export const renderConfigJsonSchema = (): string => renderJsonSchema(jackherdConfigSchema)
+
+export const renderSourcesJsonSchema = (): string => renderJsonSchema(personalSourcesSchema)

package/src/config/location.ts

@@ -50,3 +50,10 @@ export const findProjectRoot = (start: string, home: string, exists: (path: stri
  */
 export const locateConfigFile = (roots: string[], home: string, exists: (path: string) => boolean): string | null =>
   [...roots, home].flatMap(configCandidates).find(exists) ?? null
+
+export const PERSONAL_SOURCES_FILE = 'sources.json'
+
+/** The directory a personal source runs in, and holds the personal sources file. */
+export const personalSourcesDirectory = (home: string): string => join(home, TOOL_DIRECTORY)
+
+export const personalSourcesPath = (home: string): string => join(personalSourcesDirectory(home), PERSONAL_SOURCES_FILE)

package/src/config/personal-sources.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { errorMessage } from '../sync/error-message'
+import { SOURCE_ORIGIN, type SourceOrigin, type SourceSettings } from '../watch/sources'
+import { personalSourcesPath } from './location'
+import { readResolvedConfig } from './read-config'
+import { parsePersonalSourcesFile } from './schema'
+
+export type MergedSources = { sources: SourceSettings[]; notes: string[] }
+
+/** What a note starts with when an invalid personal file was left out. */
+export const PERSONAL_IGNORED = 'personal sources ignored:'
+
+const skippedPrefix = (name: string): string => `personal source ${name} in `
+
+const skippedNote = (name: string, path: string): string =>
+  `${skippedPrefix(name)}${path} skipped: the repository has a source of that name`
+
+/** Whether a merge note concerns the source `name`: the personal source of that name was skipped, or the file was ignored. */
+export const isNoteAbout = (note: string, name: string): boolean =>
+  note.startsWith(skippedPrefix(name)) || note.startsWith(PERSONAL_IGNORED)
+
+const withOrigin = (sources: readonly SourceSettings[], origin: SourceOrigin): SourceSettings[] =>
+  sources.map((source) => ({ ...source, origin }))
+
+/**
+ * The repository's sources, then the personal ones, each marked with its origin. A personal source whose name a
+ * repository source has is left out and named in a note; `path` is how the notes spell the personal file.
+ */
+export const mergedSources = (
+  repo: readonly SourceSettings[],
+  personal: readonly SourceSettings[],
+  path: string,
+): MergedSources => {
+  const repoNames = new Set(repo.map(({ name }) => name))
+  const kept = personal.filter(({ name }) => !repoNames.has(name))
+  const skipped = personal.filter(({ name }) => repoNames.has(name))
+  return {
+    sources: [...withOrigin(repo, SOURCE_ORIGIN.repo), ...withOrigin(kept, SOURCE_ORIGIN.personal)],
+    notes: skipped.map(({ name }) => skippedNote(name, path)),
+  }
+}
+
+/** The personal sources of `~/.jackherd/sources.json`, none when the file is missing; an invalid file throws with its path and the issues. */
+export const readPersonalSources = (
+  home: string = homedir(),
+  exists: (path: string) => boolean = existsSync,
+  readText: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): SourceSettings[] => {
+  const path = personalSourcesPath(home)
+  if (!exists(path)) return []
+  let raw: unknown
+  try {
+    raw = JSON.parse(readText(path))
+  } catch (error) {
+    throw new Error(`${path} is invalid: ${errorMessage(error)}`)
+  }
+  return parsePersonalSourcesFile(raw, path).sources
+}
+
+/**
+ * The repository's sources with the personal ones of `home` merged in (`mergedSources`). An invalid personal file
+ * never stops the caller: its error becomes a note and the repository's sources stand alone.
+ */
+export const sourcesWithPersonal = (
+  repo: readonly SourceSettings[],
+  home: string = homedir(),
+  exists: (path: string) => boolean = existsSync,
+  readText?: (path: string) => string,
+): MergedSources => {
+  try {
+    return mergedSources(repo, readPersonalSources(home, exists, readText), personalSourcesPath(home))
+  } catch (error) {
+    return { sources: withOrigin(repo, SOURCE_ORIGIN.repo), notes: [`${PERSONAL_IGNORED} ${errorMessage(error)}`] }
+  }
+}
+
+/**
+ * The sources of the project config of the first of `roots` that has one (`readResolvedConfig`), with the personal
+ * ones of `home` merged in; throws like `readResolvedConfig` when the project config is missing or invalid.
+ */
+export const configuredSources = (roots: string[], home: string = homedir()): MergedSources =>
+  sourcesWithPersonal(readResolvedConfig(roots, home).config.watch.sources, home)

package/src/config/schema.ts

@@ -1,9 +1,11 @@
 import { z } from 'zod'
 import { checkConfigSchema } from '../check/schema'
 import { claudePath, WORKTREES_DIRECTORY } from '../claude/paths'
+import { SECRET_NAME } from '../secrets/options'
 import { PLAN_LANGUAGE, RESPONSE_ADDRESS } from '../vocabulary'
 import { CONTENT_FIELDS, SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
+import { SOURCE_SHOW } from '../watch/sources'
 import { BUN_FAILED_TEST_PATTERN, CLEAN_REVIEW_TEXT } from '../watch/watch-defaults'
 import { MAX_AUTO_WINDOW_DAYS, windowDays } from './auto-window'
 import { DEFAULT_BASE_BRANCH } from './base-branch'
@@ -289,6 +291,17 @@ const sourceSchema = z
      * `author`, `body` and `url`; without it a change of that content reports.
      */
     reportOn: z.array(z.string().min(1)).min(1).max(10).optional(),
+    /**
+     * Names of secrets the command needs, handed to it as environment variables of the same name; each is looked up
+     * in the keychain, then in the watcher's environment.
+     */
+    secrets: z
+      .array(z.string().regex(SECRET_NAME, 'capital letters, digits and `_`, starting with a letter'))
+      .max(10)
+      .refine((names) => new Set(names).size === names.length, 'secret names must be unique')
+      .optional(),
+    /** `entries` shows the source's entries open, in a herd block of its own; not for a ticket source, whose entries are badges. */
+    show: z.literal(SOURCE_SHOW.entries).optional(),
   })
   .refine(canChange, {
     message: 'map needs updatedAt, a content field (title, author, body, url) or reportOn',
@@ -298,6 +311,10 @@ const sourceSchema = z
     message: 'ignoreAuthors needs map.author',
     path: ['ignoreAuthors'],
   })
+  .refine((source) => source.show === undefined || source.ticket !== true, {
+    message: 'show cannot be set on a ticket source',
+    path: ['show'],
+  })
   .refine((source) => !source.reportOn?.includes(SOURCE_FIELD.id), {
     message: 'reportOn cannot name id',
     path: ['reportOn'],
@@ -592,6 +609,18 @@ const parseLabelled = <T extends z.ZodType>(schema: T, raw: unknown, label: stri
 export const parseConfigFile = (raw: unknown, label: string): JackherdConfig =>
   parseLabelled(jackherdConfigSchema, raw, label)
 
+/** The personal sources file (`~/.jackherd/sources.json`): the same entries as `watch.sources`. */
+export const personalSourcesSchema = z.strictObject({
+  $schema: z.string().optional(),
+  sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
+})
+
+export type PersonalSourcesFile = z.infer<typeof personalSourcesSchema>
+
+/** The personal sources file as read from JSON; invalid throws with `label` (its path) and the issues in words. */
+export const parsePersonalSourcesFile = (raw: unknown, label: string): PersonalSourcesFile =>
+  parseLabelled(personalSourcesSchema, raw, label)
+
 /** One `watch.sources` entry outside the config, such as a draft to try; invalid throws with `label` and the issues. */
 export const parseSourceDraft = (raw: unknown, label: string): z.infer<typeof sourceSchema> =>
   parseLabelled(sourceSchema, raw, label)

package/src/plans/herd-claim.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { readFileSync, readlinkSync, unlinkSync } from 'node:fs'
+import { unlinkSync } from 'node:fs'
 import { join } from 'node:path'
 import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
 import {
@@ -9,6 +9,7 @@ import {
   systemLocation,
   userDirectoryOf,
 } from '../shared/private-location'
+import { systemProcessInfo } from '../shared/process-info'
 import { HERD_COMMAND } from './herd-command'
 import { CHILD_MARKER, TAKEN_OVER_CODE, TAKEOVER_SIGNAL } from './restart-decision'
 
@@ -96,36 +97,13 @@ export const startExclusive = async (
   start()
 }
 
-const terminalOfStdin = (): string | null => {
-  try {
-    const target = readlinkSync('/proc/self/fd/0')
-    return target.startsWith('/dev/') ? target : null
-  } catch {
-    return null
-  }
-}
+/** True when the words of a process hold the herd child's marker and the herd command. */
+export const isHerdViewWords = (words: readonly string[] | null): boolean =>
+  Boolean(words?.includes(`${CHILD_MARKER}=1`) && words.includes(HERD_COMMAND.name))
 
-const readText = (path: string): string | null => {
-  try {
-    return readFileSync(path, 'utf8')
-  } catch {
-    return null
-  }
-}
+const processInfo = systemProcessInfo()
 
-const isHerdViewProcess = (pid: number): boolean => {
-  const environment = readText(`/proc/${pid}/environ`)
-  const command = readText(`/proc/${pid}/cmdline`)
-  if (environment === null || command === null) return false
-  return environment.split('\0').includes(`${CHILD_MARKER}=1`) && command.split('\0').includes(HERD_COMMAND.name)
-}
-
-const isGoneProcess = (pid: number): boolean => {
-  const stat = readText(`/proc/${pid}/stat`)
-  if (stat === null) return true
-  const stateIndex = stat.lastIndexOf(')') + 2
-  return stat.charAt(stateIndex) === 'Z'
-}
+const isHerdViewProcess = (pid: number): boolean => isHerdViewWords(processInfo.wordsOf(pid))
 
 const signalProcess = (pid: number, signal: NodeJS.Signals): void => {
   try {
@@ -158,7 +136,7 @@ export const herdClaimDeps = (file: string): ClaimDeps => ({
     }
   },
   isHerdView: isHerdViewProcess,
-  isGone: isGoneProcess,
+  isGone: processInfo.isGone,
   signal: signalProcess,
   sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
   onExit: (run) => {
@@ -168,6 +146,6 @@ export const herdClaimDeps = (file: string): ClaimDeps => ({
 
 /** Takes the terminal of stdin over from an older herd view; without a terminal (or `/proc`) it does nothing. */
 export const claimOwnTerminal = async (): Promise<void> => {
-  const terminal = terminalOfStdin()
+  const terminal = processInfo.terminalOfStdin()
   if (terminal !== null) await claimTerminal(herdClaimDeps(recordFileOf(terminal)))
 }

package/src/plans/settings.ts

@@ -5,6 +5,8 @@ import { PROJECT_CONFIG_PATH } from '../config/location'
 import { readConfig } from '../config/read-config'
 import type { ToneName } from '../config/tones'
 import type { TicketSource } from '../watch/plan-badges'
+import type { SourceShow } from '../watch/sources'
+import { type WatchedSource, watchedSourceOf } from '../watch/watched-source'
 
 export const CONFIG_PATH = PROJECT_CONFIG_PATH
 
@@ -20,14 +22,29 @@ export type PlansSettings = Pick<
   context: JackherdConfig['plans']['context']
   /** The `watch.sources` marked `ticket`, whose entries the view shows as badges. */
   ticketSources: TicketSource[]
-  /** The other `watch.sources` by name, with the tone each names for a new report; the herd lists them in a block of their own. */
-  herdSources: { name: string; tone: ToneName | null }[]
+  /**
+   * The other `watch.sources` by name, with the tone each names for a new report and, when set, how it shows its
+   * entries; the herd lists them in a block of their own.
+   */
+  herdSources: { name: string; tone: ToneName | null; show?: SourceShow }[]
   /** By source name: what the herd puts before a row of "Your turn" that came from the source, its `label` or else its name. */
   sourceLabels: Record<string, string>
   /** The tone of each role in the herd. */
   tones: JackherdConfig['plans']['tones']
 }
 
+/** What the herd draws of the watcher's sources: from the watcher's state when it keeps them, else from the config. */
+export type HerdSourceSettings = Pick<PlansSettings, 'ticketSources' | 'herdSources' | 'sourceLabels'>
+
+/** The herd's view of `sources`, in their order: the tickets, the others with their tone and `show`, every label. */
+export const herdSourceSettingsOf = (sources: readonly WatchedSource[]): HerdSourceSettings => ({
+  ticketSources: sources.flatMap(({ name, lane, ticket }) => (ticket ? [{ name, lane }] : [])),
+  herdSources: sources.flatMap(({ name, ticket, tone, show }) =>
+    ticket ? [] : [{ name, tone, ...(show === null ? {} : { show }) }],
+  ),
+  sourceLabels: Object.fromEntries(sources.map(({ name, label }) => [name, label ?? name])),
+})
+
 /** The locale of the times the herd writes (the refresh error, the last fetch): English, with a 24-hour clock. */
 export const CLOCK_LOCALE = 'en-GB'
 
@@ -45,11 +62,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   shimmer: config.plans.shimmer,
   linkKinds: config.plans.linkKinds,
   context: config.plans.context,
-  ticketSources: config.watch.sources.flatMap(({ name, lane, ticket }) =>
-    ticket ? [{ name, lane: lane ?? null }] : [],
-  ),
-  herdSources: config.watch.sources.flatMap(({ name, ticket, tone }) => (ticket ? [] : [{ name, tone: tone ?? null }])),
-  sourceLabels: Object.fromEntries(config.watch.sources.map(({ name, label }) => [name, label ?? name])),
+  ...herdSourceSettingsOf(config.watch.sources.map(watchedSourceOf)),
   tones: config.plans.tones,
 })
 

package/src/plans/snapshot.ts

@@ -23,7 +23,7 @@ import { isRestingAgent } from '../terminal/types'
 import { laneReportPath, readLaneReport } from '../watch/lane-report-file'
 import { restNote } from '../watch/lane-rest'
 import type { SourceTicket, WatchBadges, WatchHealth } from '../watch/plan-badges'
-import { readWatchReading } from '../watch/plan-badges-read'
+import { readWatchReading, type SourcedWatchReading } from '../watch/plan-badges-read'
 import type { SourceStatus } from '../watch/source-statuses'
 import { assignSignals, laneOfDirectory, type UnplannedTask } from './active-tasks'
 import { activityLineOf, type LaneSubagents } from './activity-read'
@@ -65,7 +65,7 @@ import { markStale, type PlannedPlan, plannedPlans } from './planned'
 import type { PullRequest } from './pull-requests'
 import type { ReadCache } from './read-cache'
 import { type SentChip, sentChipsByLane } from './sent-files'
-import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from './settings'
+import { baseRefOf, boardRepoPathOf, type HerdSourceSettings, type PlansSettings, worktreeOf } from './settings'
 import { signalledTitle } from './signalled-phase'
 import { readAllSignalsSliced } from './signals-read'
 import { createSliceGate, type SliceGate } from './slice-gate'
@@ -194,7 +194,7 @@ type LaneSet = { lanes: SprintLane[]; unlisted: UnlistedLane[]; sources: LaneSou
 
 /** What a lane's view is decorated with after it was read. */
 type Decorations = {
-  reading: ReturnType<typeof readWatchReading> | null
+  reading: SourcedWatchReading | null
   phaseModels: readonly PhaseModelRecord[]
   sprintDirectory: string
   sentChips: ReadonlyMap<string | null, SentChip[]>
@@ -638,7 +638,7 @@ const decoratedViews = (
 /** Each source with the tone and the label its config gives it. */
 const withSourceStyle = (
   statuses: readonly SourceStatus[],
-  { herdSources, sourceLabels }: Pick<PlansSettings, 'herdSources' | 'sourceLabels'>,
+  { herdSources, sourceLabels }: HerdSourceSettings,
 ): HerdSource[] =>
   statuses.map((status) => {
     const label = sourceLabels[status.name]
@@ -646,6 +646,24 @@ const withSourceStyle = (
     return { ...status, tone, ...(label === undefined ? {} : { label }) }
   })
 
+/**
+ * The watcher's reading and the sources the view draws: those the watcher's state names, else the config's. The
+ * state is read every time, so a source the watcher took up since the herd started shows; the reading is null while
+ * the view follows no source and no pull request.
+ */
+const watchReadingOf = (
+  root: string,
+  now: number,
+  fallback: HerdSourceSettings,
+  results: readonly LaneResult[],
+): { reading: SourcedWatchReading | null; sourceSettings: HerdSourceSettings } => {
+  const read = readWatchReading(root, now, fallback)
+  const { ticketSources, herdSources } = read.sourceSettings
+  const watched =
+    ticketSources.length > 0 || herdSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
+  return { reading: watched ? read : null, sourceSettings: read.sourceSettings }
+}
+
 /**
  * The open phases no lane with an agent leads, a plan marked stale by its last change at `baseCommit`; none while the
  * view shows one lane.
@@ -712,25 +730,14 @@ export const loadSnapshot = async (
   const { parsed } = laneSet.sources
   const listedPlans = await readListedPlans(source, base, sprintDirectory, markdown, fallbacks)
   const documentsPlans = Object.assign({}, listedPlans, ...results.map((result) => result.texts))
-  const { ticketSources, herdSources } = settings
-  const watched =
-    ticketSources.length > 0 || herdSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
   await gate.pass()
-  const reading = watched
-    ? readWatchReading(
-        root,
-        now,
-        ticketSources,
-        undefined,
-        undefined,
-        herdSources.map(({ name }) => name),
-      )
-    : null
+  const { reading, sourceSettings } = watchReadingOf(root, now, settings, results)
+  const { ticketSources } = sourceSettings
   await gate.pass()
   const waitingRecords = readWaitingRecords(root)
   const waiting = withSourcePrefix(
     waitingItemsOf(liveBoard, settings.planLanguage, waitingRecords, now),
-    settings.sourceLabels,
+    sourceSettings.sourceLabels,
   )
   const sentChips = sentChipsByLane(waitingRecords.sent, worktrees, now)
   const notice = fallbacks.length > 0 ? fallbackNotice(fallbacks, baseRef, refExists(root, baseRef)) : null
@@ -782,7 +789,7 @@ export const loadSnapshot = async (
     waiting,
     groomedDays: groomedDaysAgo(liveBoard, settings.planLanguage, new Date(now)),
     yourTurn: yourTurnOfBoard(liveBoard, settings.planLanguage, waiting, now),
-    ...(reading?.sources ? { sourceBlock: { sources: withSourceStyle(reading.sources, settings), now } } : {}),
+    ...(reading?.sources ? { sourceBlock: { sources: withSourceStyle(reading.sources, sourceSettings), now } } : {}),
     tones: settings.tones,
     ...(coordinator ? { coordinator: coordinator.view } : {}),
     unplaced: unplacedOf(unplacedSources, laneSet.lanes, Boolean(options.lane)),