jackherd 1.15.2 → 1.17.0

package/src/watch/single-report.ts

@@ -9,7 +9,8 @@ export const SINGLE_REPORT_NOTICE =
 export const NO_MONITOR_NOTICE =
   'watch ended after this report. This session has no Monitor tool, so a single call is the way it works here: start it again as a background Bash call (run_in_background) after you acted on this report.'
 
-export const withSingleReportNotice = (lines: readonly string[], monitorAvailable: boolean): string[] => [
+/** The report with its closing notice; without a Monitor tool the notice carries `hint`, the reference that explains the restart. */
+export const withSingleReportNotice = (lines: readonly string[], monitorAvailable: boolean, hint = ''): string[] => [
   ...lines,
-  monitorAvailable ? SINGLE_REPORT_NOTICE : NO_MONITOR_NOTICE,
+  monitorAvailable ? SINGLE_REPORT_NOTICE : `${NO_MONITOR_NOTICE}${hint}`,
 ]

package/src/watch/source-dry-run-command.ts

@@ -1,6 +1,7 @@
 import { homedir } from 'node:os'
 import { personalSourcesPath } from '../config/location'
-import { configuredSources, isNoteAbout } from '../config/personal-sources'
+import { configuredSources, type ExcludedSource, excludedNote, isNoteAbout } from '../config/personal-sources'
+import { readRepositoryIdentity } from '../config/repository-identity'
 import { parseSourceDraft } from '../config/schema'
 import { mainCheckout, worktreeRoot } from '../plans/git'
 import type { SourceDryRun } from './options'
@@ -18,18 +19,35 @@ const settingsOf = async (target: DryRunTarget, sources: readonly SourceSettings
   return parseSourceDraft(JSON.parse(text), target.kind === 'stdin' ? 'stdin' : target.path)
 }
 
+/** Exit code of a dry run of a source that is not for this repository: nothing ran. */
+export const NOT_FOR_THIS_REPO_EXIT = 2
+
+/** The note of the personal source the dry run names when its `repos` leave this repository out; null for any other target. */
+export const excludedNoteFor = (target: DryRunTarget, excluded: readonly ExcludedSource[]): string | null => {
+  if (target.kind !== 'name') return null
+  const found = excluded.find(({ source }) => source.name === target.name)
+  return found ? excludedNote(found) : null
+}
+
 /**
  * `jh watch source <name|draft.json|-> --dry-run [--raw]`: runs one source once in the main checkout (a personal one in `~/.jackherd`), as the
  * watcher would, its `secrets` handed to the command alike, and prints what it found and would report; `--raw` adds
  * the command's stdout, which by the recipe rules carries no secret value. Takes no lock and
  * neither reads nor writes the watcher's state, so a running watcher is not disturbed. Exits 1 when the run failed or a
- * `map` field is empty in every entry.
+ * `map` field is empty in every entry, and 2, running nothing, when the named personal source is not for this
+ * repository (its `repos`).
  */
 export const sourceDryRun = async ({ target, raw }: SourceDryRun): Promise<number> => {
   const root = mainCheckout(process.cwd())
   const home = homedir()
-  const merged = configuredSources([worktreeRoot(process.cwd()), root], home)
-  const settings = await settingsOf(dryRunTarget(target), merged.sources)
+  const merged = configuredSources([worktreeRoot(process.cwd()), root], readRepositoryIdentity(root), home)
+  const named = dryRunTarget(target)
+  const excluded = excludedNoteFor(named, merged.excluded)
+  if (excluded !== null) {
+    console.log(excluded)
+    return NOT_FOR_THIS_REPO_EXIT
+  }
+  const settings = await settingsOf(named, merged.sources)
   const answer = await sourceAnswer(settings, root, SOURCE_LIMITS, home)
   const run = sourceRunOf(settings, answer)
   const mapCheck = answer.ok ? emptyMapFields(answer.stdout, settings) : null

package/src/watch/source-dry-run.ts

@@ -35,7 +35,7 @@ const RAW_LINE_LENGTH = 200
 const INDENT = '  '
 const BASELINE = 'first run of this source: baseline, nothing reported'
 const NOT_CHECKED = '0 entries: map not checked'
-const FOOTER = 'watcher state not read or changed; the watcher takes a new source over at its next start'
+const FOOTER = 'watcher state not read or changed; a running watcher takes a new source over at its next cycle'
 
 export const dryRunTarget = (value: string): DryRunTarget => {
   if (value === STDIN) return { kind: 'stdin' }

package/src/watch/source-reason.ts

@@ -0,0 +1,58 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+/** The start of the one stdout line a failing source's command may give its reason in. */
+export const SOURCE_REASON_PREFIX = 'jackherd-reason:'
+
+export const SOURCE_REASON_MAX_LENGTH = 160
+
+/**
+ * A reason line past this length is dropped before any pattern reads it: a real reason is short, and the masking
+ * patterns backtrack on a long line from a command that passes outside text through.
+ */
+export const SOURCE_REASON_MAX_INPUT = 1024
+
+const MASK = '***'
+
+/** The whole authority up to its last `@`, which WHATWG URLs split the credentials at. */
+const URL_CREDENTIALS = /(?<![a-z0-9+.-])([a-z][a-z0-9+.-]*:\/\/)[^\s/?#]*@/gi
+
+const QUERY_VALUE = /([?&#][^\s=&#?]+=)[^\s&#]*/g
+
+const lastReasonLine = (stdout: string): string | null => {
+  const lines = stdout.split('\n').filter((line) => line.trimStart().startsWith(SOURCE_REASON_PREFIX))
+  const last = lines.at(-1)
+  return last === undefined ? null : last.trimStart().slice(SOURCE_REASON_PREFIX.length)
+}
+
+/** A value as stored and as a script may print it: without control characters, without surrounding blanks. */
+const printedFormsOf = (value: string): string[] => [
+  value,
+  value.trim(),
+  terminalSafe(value),
+  terminalSafe(value).trim(),
+]
+
+const withoutSecrets = (text: string, secretValues: readonly string[]): string =>
+  [...new Set(secretValues.flatMap(printedFormsOf))]
+    .filter((value) => value.length > 0)
+    .sort((a, b) => b.length - a.length)
+    .reduce((masked, value) => masked.replaceAll(value, MASK), text)
+
+const withoutUrlAccess = (text: string): string =>
+  text.replace(URL_CREDENTIALS, `$1${MASK}@`).replace(QUERY_VALUE, `$1${MASK}`)
+
+/**
+ * The reason a failing source's command gives on stdout: the last line starting with `SOURCE_REASON_PREFIX`, with
+ * every value of `secretValues` (the source's own `secrets`), credentials and query values of URLs masked and
+ * control characters dropped, then cut to `SOURCE_REASON_MAX_LENGTH`. Secrets are masked before and after the control
+ * characters go, so one split by them is found too. A token the source took from elsewhere is not recognised; the
+ * recipes' rule keeps it out of the line. Null without such a line, with nothing in it, or with one longer than
+ * `SOURCE_REASON_MAX_INPUT`.
+ */
+export const sourceReason = (stdout: string, secretValues: readonly string[]): string | null => {
+  const line = lastReasonLine(stdout)
+  if (line === null || line.length > SOURCE_REASON_MAX_INPUT) return null
+  const cleaned = withoutUrlAccess(withoutSecrets(terminalSafe(withoutSecrets(line, secretValues)), secretValues))
+  const reason = cleaned.trim()
+  return reason.length > 0 ? ellipsize(reason, SOURCE_REASON_MAX_LENGTH) : null
+}

package/src/watch/source-reload.ts

@@ -1,8 +1,7 @@
-import { existsSync, statSync } from 'node:fs'
+import { statSync } from 'node:fs'
 import { join } from 'node:path'
-import { locateConfigFile, PROJECT_CONFIG_PATH, personalSourcesPath } from '../config/location'
+import { PROJECT_CONFIG_PATH, personalSourcesPath } from '../config/location'
 import { mergedSources, readPersonalSources } from '../config/personal-sources'
-import { readResolvedConfig } from '../config/read-config'
 import { errorText } from '../plans/error-text'
 import type { SourceSettings } from './sources'
 
@@ -16,7 +15,7 @@ export type LoadedSources = { sources: SourceSettings[]; stamps: FileStamps }
 export type SourceFileReader = { path: string; read: () => readonly SourceSettings[] }
 
 /** A file that could not be read, as the line the watcher prints. */
-type ReadFailure = { ok: false; line: string }
+export type ReadFailure = { ok: false; line: string }
 
 /** A reading of both files: the merged sources with the notes of the skipped ones, or the line naming the file that failed. */
 export type SourceRead = { ok: true; sources: SourceSettings[]; notes: string[] } | ReadFailure
@@ -30,7 +29,7 @@ const sameStamps = (previous: FileStamps, current: FileStamps): boolean => {
 }
 
 /** The error of `path` on one line, without the `<path> is invalid:` the config readers put before the issues. */
-const reasonOf = (path: string, error: unknown): string =>
+export const reasonOf = (path: string, error: unknown): string =>
   errorText(error).replace(`${path} is invalid:`, '').replace(/\s+/g, ' ').trim()
 
 const readOne = (reader: SourceFileReader): { ok: true; sources: readonly SourceSettings[] } | ReadFailure => {
@@ -41,13 +40,20 @@ const readOne = (reader: SourceFileReader): { ok: true; sources: readonly Source
   }
 }
 
-/** Reads the repository's sources, then the personal ones, and merges them (`mergedSources`); the first file that fails is named. */
-export const readSourceFiles = (repo: SourceFileReader, personal: SourceFileReader): SourceRead => {
+/**
+ * Reads the repository's sources, then the personal ones, and merges them for the repository `identity`
+ * (`mergedSources`); the first file that fails is named.
+ */
+export const readSourceFiles = (
+  repo: SourceFileReader,
+  personal: SourceFileReader,
+  identity: string | null,
+): SourceRead => {
   const repoRead = readOne(repo)
   if (!repoRead.ok) return repoRead
   const personalRead = readOne(personal)
   if (!personalRead.ok) return personalRead
-  return { ok: true, ...mergedSources(repoRead.sources, personalRead.sources, personal.path) }
+  return { ok: true, ...mergedSources(repoRead.sources, personalRead.sources, personal.path, identity) }
 }
 
 /**
@@ -85,16 +91,14 @@ export const readFileStamps = (paths: readonly string[]): FileStamps =>
   Object.fromEntries(paths.map((path) => [path, changeTimeOf(path)]))
 
 /**
- * Reads the sources again: `watch.sources` of the config `readResolvedConfig` finds in `roots` (the rest of the config
- * is not taken over), and those of the personal file of `home`. Unlike the start (`sourcesWithPersonal`), where an
- * invalid personal file leaves the repository's sources alone, here it keeps the list the watcher runs: both keep
- * what ran before, which at the start is no personal source.
+ * Reads the sources again: the repository's (`repository`, the config as `readWatchedConfig` read it) and those of the
+ * personal file of `home` that are for the repository `identity`. Unlike the start (`sourcesWithPersonal`), where an invalid personal file leaves the
+ * repository's sources alone, here it keeps the list the watcher runs: both keep what ran before, which at the start
+ * is no personal source.
  */
-export const readWatchedSources = (roots: string[], home: string): SourceRead =>
+export const readWatchedSources = (repository: SourceFileReader, home: string, identity: string | null): SourceRead =>
   readSourceFiles(
-    {
-      path: locateConfigFile(roots, home, existsSync) ?? join(roots[0] ?? home, PROJECT_CONFIG_PATH),
-      read: () => readResolvedConfig(roots, home).config.watch.sources,
-    },
+    repository,
     { path: personalSourcesPath(home), read: (): SourceSettings[] => readPersonalSources(home) },
+    identity,
   )

package/src/watch/source-run.ts

@@ -3,6 +3,7 @@ import { personalSourcesDirectory } from '../config/location'
 import { type Environment, sourceEnvironment } from '../secrets/environment'
 import { SECRET_LOOKUP, SECRET_TIMEOUT_MS, type SecretLookupFn, secretStore } from '../secrets/store'
 import { resolveSourceCommand } from './source-command'
+import { sourceReason } from './source-reason'
 import {
   exitFailure,
   parseSourceOutput,
@@ -27,8 +28,10 @@ const TOO_LARGE_ANSWER: SourceAnswer = { ok: false, reason: SOURCE_FAILURE.tooLa
 const UNREADABLE_ANSWER: SourceAnswer = { ok: false, reason: SOURCE_FAILURE.unreadable }
 const READ_FAILED = Symbol('read failed')
 
-const answerOf = (stdout: string, exitCode: number): SourceAnswer =>
-  exitCode === 0 ? { ok: true, stdout } : { ok: false, reason: exitFailure(exitCode) }
+const answerOf = (stdout: string, exitCode: number, secretValues: readonly string[]): SourceAnswer =>
+  exitCode === 0
+    ? { ok: true, stdout }
+    : { ok: false, reason: exitFailure(exitCode, sourceReason(stdout, secretValues)) }
 
 /** The run a command's answer makes: its output over `items` and `map`, or the reason it failed. */
 export const sourceRunOf = (settings: SourceSettings, answer: SourceAnswer): SourceRun => ({
@@ -76,7 +79,8 @@ const killGroup = (child: Child) => {
 /**
  * Runs `command` as given, without a shell, in `cwd` with `env` (the user's environment without it); never rejects.
  * `env` reaches the command only: it is neither an argument nor printed. stderr is not read,
- * so nothing a failing tool prints there (a token, a URL with credentials) reaches the report. Past `timeoutMs` or
+ * so nothing a failing tool prints there (a token, a URL with credentials) reaches the report. A non-zero exit keeps
+ * stdout's `jackherd-reason:` line only, cleaned of `secretValues` (`sourceReason`). Past `timeoutMs` or
  * `maxBytes` the command's process group is killed, and the answer never waits past `timeoutMs` for a pipe a leftover
  * process keeps open; the group is also killed after a normal end, so a source leaves no process behind that stays in its group.
  */
@@ -85,6 +89,7 @@ export const runSourceCommand = async (
   cwd: string,
   limits: SourceLimits,
   env?: Environment,
+  secretValues: readonly string[] = [],
 ): Promise<SourceAnswer> => {
   const child = spawned(command, cwd, env)
   if (!child) return { ok: false, reason: SOURCE_FAILURE.notStarted }
@@ -99,7 +104,7 @@ export const runSourceCommand = async (
     if (stdout === null) return TOO_LARGE_ANSWER
     if (stdout === READ_FAILED) return UNREADABLE_ANSWER
     const exitCode = await Promise.race([child.exited, deadline])
-    return exitCode === TIMED_OUT ? TIMED_OUT_ANSWER : answerOf(stdout, exitCode)
+    return exitCode === TIMED_OUT ? TIMED_OUT_ANSWER : answerOf(stdout, exitCode, secretValues)
   } finally {
     clearTimeout(timer)
     killGroup(child)
@@ -126,10 +131,14 @@ const noKeychain: SecretLookupFn = async () => ({ kind: SECRET_LOOKUP.absent })
 export const secretLookupFor = (settings: Pick<SourceSettings, 'origin'>, keychain: SecretLookupFn): SecretLookupFn =>
   settings.origin === SOURCE_ORIGIN.personal ? keychain : noKeychain
 
+/** The values of the run's own `secrets`, which its reason must not show. */
+const secretValuesOf = (names: readonly string[], environment: Environment): string[] =>
+  names.flatMap((name) => environment[name] ?? [])
+
 /**
  * The answer of a source's command in `sourceDirectory`, its `secrets` resolved first (`sourceEnvironment` over
  * `secretLookupFor`, looked up afresh on each run and dropped after it). A secret that cannot be resolved fails the run
- * before the command starts.
+ * before the command starts. The values also clean the reason of a failed run.
  */
 export const sourceAnswer = async (
   settings: SourceSettings,
@@ -138,9 +147,17 @@ export const sourceAnswer = async (
   home: string = homedir(),
   lookup: SecretLookupFn = keychainLookup(limits),
 ): Promise<SourceAnswer> => {
-  const environment = await sourceEnvironment(settings.secrets ?? [], secretLookupFor(settings, lookup), process.env)
+  const names = settings.secrets ?? []
+  const environment = await sourceEnvironment(names, secretLookupFor(settings, lookup), process.env)
   if (!environment.ok) return environment
-  return runSourceCommand(settings.command, sourceDirectory(settings, root, home), limits, environment.environment)
+  const directory = sourceDirectory(settings, root, home)
+  return runSourceCommand(
+    settings.command,
+    directory,
+    limits,
+    environment.environment,
+    secretValuesOf(names, environment.environment),
+  )
 }
 
 /** One run of a source in `sourceDirectory`: its secrets and command (`sourceAnswer`), then its output over `items` and `map`. */

package/src/watch/sources.ts

@@ -12,7 +12,10 @@ 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`. */
+/**
+ * Why a run of a source failed, as a class only: never its stderr, which may carry a token. `exit <code>` and its
+ * reason come from `exitFailure`.
+ */
 export const SOURCE_FAILURE = {
   timeout: 'timeout',
   tooLarge: 'output too large',
@@ -69,6 +72,8 @@ export type SourceSettings = {
   show?: SourceShow
   /** Where the source is defined; without it the repository's config. */
   origin?: SourceOrigin
+  /** `owner/name` of the repositories a personal source runs in; without it every repository. Never in the repository's config. */
+  repos?: readonly string[]
   /** Shown before the source's rows in the herd; without it its name. */
   label?: string
   /** The tone of its mark in the herd while its newest report is new. */
@@ -177,7 +182,9 @@ const STORED_PREFIX_LENGTH = 180
 const VALUE_HASH_LENGTH = 8
 const MINUTE_MS = 60_000
 
-export const exitFailure = (code: number): string => `exit ${code}`
+/** `exit <code>`, with the cleaned reason of the command's `jackherd-reason:` line (`sourceReason`) when it gave one. */
+export const exitFailure = (code: number, reason: string | null = null): string =>
+  reason ? `exit ${code}: ${reason}` : `exit ${code}`
 
 export const emptySourceState = (): SourceState => ({})
 

package/src/watch/texts.ts

@@ -18,7 +18,12 @@ export type WatchTexts = {
   /** The prefix of a merge's duty line, with the pull request number. */
   afterMerge: (number: number) => string
   mergedLaneDuty: string
+  mergedWithOpenBoxes: (phase: string, lines: readonly number[]) => string
   otherLaneDuty: string
+  /** After the rebase of a lane the merge reached: every check, those of the named roots (`a, b`), or none. */
+  mergeChecksAll: string
+  mergeChecksRoots: (roots: string) => string
+  mergeChecksNone: string
   blockedDuty: string
   /** What a lane whose context reached `alert` asks of the coordinator. */
   laneAlertDuty: string
@@ -46,6 +51,7 @@ export type WatchTexts = {
 
 /** The mark the approval gate hook reads from the question, as its `requestMark` writes it (contract test). */
 const approvalMark = (id: string, hash: string): string => `\`approval ${id} ${hash}\``
+const renameCommand = (name: string): string => `herdr agent rename "$HERDR_PANE_ID" ${name}`
 
 /**
  * The watcher's words: English whatever the project's languages. Only the two option labels in the approval duty follow
@@ -63,11 +69,16 @@ export const watchTexts = (dialogLanguage: PlanLanguage): WatchTexts => ({
   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}`,
+  unnamedPane: (name) => `pane without a name, ${renameCommand(name)}`,
+  noAgentNamed: (name) => `no agent named ${name}, ${renameCommand(name)}`,
   afterMerge: (number) => `after merge #${number}`,
   mergedLaneDuty: 'start the next phase or close the lane',
+  mergedWithOpenBoxes: (phase, lines) =>
+    `${phase} merged with ${lines.length} open ${lines.length === 1 ? 'box' : 'boxes'} at ${lines.join(', ')}`,
   otherLaneDuty: 'rebase, then start the next phase or name the reason to wait',
+  mergeChecksAll: 'checks: all',
+  mergeChecksRoots: (roots) => `checks: ${roots}`,
+  mergeChecksNone: 'checks: none (no overlap)',
   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)',
@@ -79,12 +90,12 @@ export const watchTexts = (dialogLanguage: PlanLanguage): WatchTexts => ({
   laneModelDuty:
     'switch it while idle: /exit, then claude --resume <session> --model <id> in the same pane (§ 2 step 6)',
   readyPhaseDuty: (count) =>
-    `start ${count === 1 ? 'it' : 'them'} now (§ 2); a waiting PR approval holds only the commit`,
+    `start ${count === 1 ? 'it' : 'them'} now (§ 2), on a branch over the open PR of the lane if it waits for approval or merge: that holds only the commit`,
   mainCheckoutBehind: (remoteBase, count) =>
     `main checkout behind ${remoteBase} by ${count} (git merge --ff-only ${remoteBase})`,
   mainCheckoutOffBase: (branch, baseBranch) => `main checkout on ${branch ?? 'a detached head'}, not ${baseBranch}`,
   checkoutRows: (term, count) => `${term}: ${count} ${count === 1 ? 'row' : 'rows'} only in the checkout`,
   otherPullRequests: 'other PRs',
   approvalDuty: (id, hash) =>
-    `ask through AskUserQuestion, the question contains ${approvalMark(id, hash)} (hash as in the file shown), options "${APPROVAL_TEXTS[dialogLanguage].allow}" and "${APPROVAL_TEXTS[dialogLanguage].deny}" (§ 4)`,
+    `show the request file in a code block, then ask through AskUserQuestion, the question contains ${approvalMark(id, hash)} (hash as in the file shown), options "${APPROVAL_TEXTS[dialogLanguage].allow}" and "${APPROVAL_TEXTS[dialogLanguage].deny}" (§ 4)`,
 })

package/src/watch/waiting-line.ts

@@ -9,11 +9,12 @@ const itemText = ({ item }: WaitingItem): string => ellipsize(terminalSafe(item)
 
 /**
  * The line that brings back what waits on the user's answer, in every heartbeat and status until the item is closed:
- * `for you (<n>): <item>; …`, three items and `+<n>` for the rest. Null when no item is open.
+ * `for you (<n>): <item>; …`, three items and `+<n>` for the rest. Null when no item is open. The heartbeat passes no
+ * `hint`, so it stays short; the status passes the one of the reference that holds the handling.
  */
-export const waitingLine = (items: readonly WaitingItem[]): string | null => {
+export const waitingLine = (items: readonly WaitingItem[], hint = ''): string | null => {
   const open = items.filter(({ open: isOpen }) => isOpen)
   if (open.length === 0) return null
   const { shown, more } = shownWithMore(open, SHOWN_ITEMS)
-  return `for you (${open.length}): ${[...shown.map(itemText), ...(more > 0 ? [`+${more}`] : [])].join('; ')}`
+  return `for you (${open.length}): ${[...shown.map(itemText), ...(more > 0 ? [`+${more}`] : [])].join('; ')}${hint}`
 }