jackherd 1.15.2 → 1.17.0

package/recipes/sources/google-calendar-today.ts

@@ -0,0 +1,38 @@
+// Copy to ~/.jackherd/sources/google-calendar-today.ts together with google-calendar.ts; the recipe
+// recipes/google-calendar.md says what to fill in. Today's appointments of the calendars whose secret
+// iCal addresses sit in GOOGLE_CALENDAR_ICS_URL, GOOGLE_CALENDAR_ICS_URL_2, … (the entry's `secrets`).
+// One entry per occurrence, so a moved or renamed appointment reports as a change and a new day brings
+// its appointments in as new. One calendar that cannot be read fails the whole run.
+import { addressesOf, civilOf, occurrencesOn, parseIcs, toItems } from './google-calendar'
+
+const zone = Intl.DateTimeFormat().resolvedOptions().timeZone
+
+// The watcher shows this line with the exit code; it never names an address, the address is the credential.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
+const addresses = addressesOf(process.env)
+if (addresses.length === 0) fail('GOOGLE_CALENDAR_ICS_URL not set')
+
+// The address is the credential: nothing from a failed request (error text, URL) may reach stderr.
+const readCalendar = async (address: string): Promise<string | undefined> => {
+  try {
+    const answer = await fetch(address, { signal: AbortSignal.timeout(20_000) })
+    const text = answer.status === 200 ? await answer.text() : ''
+    return text.includes('BEGIN:VCALENDAR') ? text : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const answers = await Promise.all(addresses.map(readCalendar))
+const texts = answers.filter((text) => text !== undefined)
+if (texts.length < answers.length) fail(`${answers.length - texts.length} of ${answers.length} calendars unreadable`)
+
+const today = civilOf(Date.now(), zone)
+const events = texts.flatMap((text) => parseIcs(text, zone))
+console.log(JSON.stringify(toItems(occurrencesOn(events, today, zone), today, zone)))
+
+export {}

package/recipes/sources/google-calendar.ts

@@ -0,0 +1,368 @@
+// The iCalendar reader of the Google Calendar recipe (recipes/google-calendar.md). Copy it next to
+// google-calendar-today.ts; the zone every function reads a wall-clock time in is an argument.
+export type Civil = { year: number; month: number; day: number; hour: number; minute: number; second: number }
+export type IcsDate = { civil: Civil; allDay: boolean; zone: string }
+export const FREQUENCY = { daily: 'DAILY', weekly: 'WEEKLY', monthly: 'MONTHLY', yearly: 'YEARLY' } as const
+export type Frequency = (typeof FREQUENCY)[keyof typeof FREQUENCY]
+export const isFrequency = (value: string): value is Frequency => (Object.values(FREQUENCY) as string[]).includes(value)
+export const EVENT_STATUS = { cancelled: 'CANCELLED' } as const
+
+export type Rule = {
+  freq: Frequency | undefined
+  interval: number
+  until?: IcsDate
+  count?: number
+  byDay: { ordinal: number; weekday: number }[]
+  byMonthDay: number[]
+  byMonth: number[]
+  unsupported: boolean
+}
+export type IcsEvent = {
+  uid: string
+  summary: string
+  location: string
+  status: string
+  lastModified?: IcsDate
+  start: IcsDate
+  end?: IcsDate
+  rule?: Rule
+  exDates: string[]
+  recurrenceId?: IcsDate
+}
+export type Occurrence = { event: IcsEvent; key: string; startMs: number; endMs: number }
+export type CalendarItem = {
+  id: string
+  title: string
+  url: string
+  updatedAt: string
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const WEEKDAYS = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']
+const UNSUPPORTED_PARTS = ['BYSETPOS', 'BYWEEKNO', 'BYYEARDAY', 'BYHOUR', 'BYMINUTE', 'BYSECOND']
+const PROPERTY_LINE = /^([A-Za-z-]+)((?:;[^:;=]+=(?:"[^"]*"|[^:;]*))*):(.*)$/
+const UNFOLD = /\r?\n[ \t]/g
+const UTC = 'UTC'
+const ADDRESS_VARIABLE = /^GOOGLE_CALENDAR_ICS_URL(?:_(\d+))?$/
+
+/** The calendar addresses in the environment, GOOGLE_CALENDAR_ICS_URL first, then `_2`, `_3`, … */
+export const addressesOf = (environment: Record<string, string | undefined>): string[] =>
+  Object.entries(environment)
+    .flatMap(([name, value]) => {
+      const match = ADDRESS_VARIABLE.exec(name)
+      return match && value ? [{ order: Number(match[1] ?? 1), value }] : []
+    })
+    .sort((a, b) => a.order - b.order)
+    .map(({ value }) => value)
+
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+const formatterFor = (zone: string): Intl.DateTimeFormat => {
+  const cached = formatters.get(zone)
+  if (cached) return cached
+  const formatter = new Intl.DateTimeFormat('en-US', {
+    timeZone: zone,
+    hourCycle: 'h23',
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: 'numeric',
+    second: 'numeric',
+  })
+  formatters.set(zone, formatter)
+  return formatter
+}
+
+export const civilOf = (ms: number, zone: string): Civil => {
+  const parts = Object.fromEntries(formatterFor(zone).formatToParts(new Date(ms)).map((part) => [part.type, part.value]))
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    hour: Number(parts.hour),
+    minute: Number(parts.minute),
+    second: Number(parts.second),
+  }
+}
+
+const civilMs = (civil: Civil): number =>
+  Date.UTC(civil.year, civil.month - 1, civil.day, civil.hour, civil.minute, civil.second)
+
+const offsetAt = (ms: number, zone: string): number => civilMs(civilOf(ms, zone)) - Math.floor(ms / 1000) * 1000
+
+/** The instant a wall-clock time in `zone` names; in a DST gap it lands one hour later. */
+export const instantOf = (civil: Civil, zone: string): number => {
+  if (zone === UTC) return civilMs(civil)
+  const guess = civilMs(civil)
+  const first = guess - offsetAt(guess, zone)
+  return guess - offsetAt(first, zone)
+}
+
+const addDays = (civil: Civil, days: number): Civil => {
+  const shifted = new Date(civilMs(civil) + days * DAY_MS)
+  return {
+    ...civil,
+    year: shifted.getUTCFullYear(),
+    month: shifted.getUTCMonth() + 1,
+    day: shifted.getUTCDate(),
+  }
+}
+
+const dayNumber = (civil: Civil): number => Math.floor(Date.UTC(civil.year, civil.month - 1, civil.day) / DAY_MS)
+const weekdayOf = (civil: Civil): number => new Date(Date.UTC(civil.year, civil.month - 1, civil.day)).getUTCDay()
+const daysInMonth = (civil: Civil): number => new Date(Date.UTC(civil.year, civil.month, 0)).getUTCDate()
+const dateKey = (civil: Civil): string =>
+  `${civil.year}${String(civil.month).padStart(2, '0')}${String(civil.day).padStart(2, '0')}`
+
+const unescapeText = (value: string): string =>
+  value.replace(/\\([\\,;nN])/g, (_, character: string) => (character.toLowerCase() === 'n' ? '\n' : character))
+
+const parseParameters = (raw: string): Record<string, string> =>
+  Object.fromEntries(
+    raw
+      .split(';')
+      .filter(Boolean)
+      .map((pair) => {
+        const [name, ...value] = pair.split('=')
+        return [name.toUpperCase(), value.join('=').replace(/^"|"$/g, '')]
+      }),
+  )
+
+const parseIcsDate =(value: string, parameters: Record<string, string>, floatingZone: string): IcsDate => {
+  const match = /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2})(Z)?)?$/.exec(value.trim())
+  if (!match) throw new Error('unreadable date')
+  const [, year, month, day, hour, minute, second, utc] = match
+  const allDay = hour === undefined
+  return {
+    civil: {
+      year: Number(year),
+      month: Number(month),
+      day: Number(day),
+      hour: Number(hour ?? 0),
+      minute: Number(minute ?? 0),
+      second: Number(second ?? 0),
+    },
+    allDay,
+    zone: utc ? UTC : (parameters.TZID ?? floatingZone),
+  }
+}
+
+const parseWeekday = (token: string): { ordinal: number; weekday: number } => {
+  const match = /^([+-]?\d+)?([A-Z]{2})$/.exec(token)
+  return { ordinal: Number(match?.[1] ?? 0), weekday: WEEKDAYS.indexOf(match?.[2] ?? '') }
+}
+
+const numbers = (value?: string): number[] => (value ? value.split(',').map(Number) : [])
+
+export const parseRule = (value: string, floatingZone: string): Rule => {
+  const parts = Object.fromEntries(value.split(';').map((pair) => pair.split('=') as [string, string]))
+  return {
+    freq: isFrequency(parts.FREQ ?? '') ? (parts.FREQ as Frequency) : undefined,
+    interval: Number(parts.INTERVAL ?? 1),
+    until: parts.UNTIL ? parseIcsDate(parts.UNTIL, {}, floatingZone) : undefined,
+    count: parts.COUNT ? Number(parts.COUNT) : undefined,
+    byDay: parts.BYDAY ? parts.BYDAY.split(',').map(parseWeekday) : [],
+    byMonthDay: numbers(parts.BYMONTHDAY),
+    byMonth: numbers(parts.BYMONTH),
+    unsupported: !isFrequency(parts.FREQ ?? '') || UNSUPPORTED_PARTS.some((part) => part in parts),
+  }
+}
+
+const occurrenceKey = (date: IcsDate): string =>
+  date.allDay ? dateKey(date.civil) : new Date(instantOf(date.civil, date.zone)).toISOString()
+
+type Property = { name: string; parameters: Record<string, string>; value: string }
+
+const readProperties = (block: string[]): Property[] =>
+  block.flatMap((line) => {
+    const match = PROPERTY_LINE.exec(line)
+    return match ? [{ name: match[1].toUpperCase(), parameters: parseParameters(match[2]), value: match[3] }] : []
+  })
+
+const buildEvent = (properties: Property[], floatingZone: string): IcsEvent | undefined => {
+  const first = (name: string) => properties.find((property) => property.name === name)
+  const date = (name: string) => {
+    const property = first(name)
+    return property ? parseIcsDate(property.value, property.parameters, floatingZone) : undefined
+  }
+  const start = date('DTSTART')
+  const uid = first('UID')?.value
+  if (!start || !uid) return undefined
+  const rule = first('RRULE')
+  return {
+    uid,
+    summary: unescapeText(first('SUMMARY')?.value ?? ''),
+    location: unescapeText(first('LOCATION')?.value ?? ''),
+    status: (first('STATUS')?.value ?? '').toUpperCase(),
+    lastModified: date('LAST-MODIFIED'),
+    start,
+    end: date('DTEND'),
+    rule: rule ? parseRule(rule.value, floatingZone) : undefined,
+    exDates: properties
+      .filter((property) => property.name === 'EXDATE')
+      .flatMap((property) =>
+        property.value.split(',').map((value) => occurrenceKey(parseIcsDate(value, property.parameters, floatingZone))),
+      ),
+    recurrenceId: date('RECURRENCE-ID'),
+  }
+}
+
+const toEvent = (properties: Property[], floatingZone: string): IcsEvent | undefined => {
+  try {
+    return buildEvent(properties, floatingZone)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The VEVENTs of an iCalendar text. A floating time (no TZID, no Z) is read in `floatingZone`;
+ * a block without UID or DTSTART, or with a date it cannot read, is dropped on its own and
+ * leaves the other events alone.
+ */
+export const parseIcs = (text: string, floatingZone: string): IcsEvent[] => {
+  const events: IcsEvent[] = []
+  let block: string[] | undefined
+  for (const line of text.replace(UNFOLD, '').split(/\r?\n/)) {
+    if (line === 'BEGIN:VEVENT') block = []
+    else if (line === 'END:VEVENT' && block) {
+      const event = toEvent(readProperties(block), floatingZone)
+      if (event) events.push(event)
+      block = undefined
+    } else block?.push(line)
+  }
+  return events
+}
+
+const monthsBetween = (from: Civil, to: Civil): number => (to.year - from.year) * 12 + (to.month - from.month)
+
+const matchesByDay = (rule: Rule, candidate: Civil): boolean =>
+  rule.byDay.some(({ ordinal, weekday }) => {
+    if (weekday !== weekdayOf(candidate)) return false
+    if (ordinal === 0) return true
+    const fromStart = Math.floor((candidate.day - 1) / 7) + 1
+    const fromEnd = -(Math.floor((daysInMonth(candidate) - candidate.day) / 7) + 1)
+    return ordinal === fromStart || ordinal === fromEnd
+  })
+
+const matchesMonthDay = (rule: Rule, candidate: Civil): boolean =>
+  rule.byMonthDay.some((day) => (day > 0 ? day : daysInMonth(candidate) + day + 1) === candidate.day)
+
+const matchesMonthly = (rule: Rule, start: Civil, candidate: Civil): boolean => {
+  if (rule.byMonthDay.length > 0) return matchesMonthDay(rule, candidate)
+  if (rule.byDay.length > 0) return matchesByDay(rule, candidate)
+  return candidate.day === start.day
+}
+
+/** Whether a rule with its DTSTART on `start` falls on the civil day `candidate` (on or after `start`). */
+export const ruleMatches = (rule: Rule, start: Civil, candidate: Civil): boolean => {
+  if (rule.byMonth.length > 0 && !rule.byMonth.includes(candidate.month)) return false
+  const days = dayNumber(candidate) - dayNumber(start)
+  if (rule.freq === FREQUENCY.daily) return days % rule.interval === 0
+  if (rule.freq === FREQUENCY.weekly) {
+    const mondayOf = (civil: Civil) => dayNumber(civil) - ((weekdayOf(civil) + 6) % 7)
+    const weeks = (mondayOf(candidate) - mondayOf(start)) / 7
+    const weekdays = rule.byDay.length > 0 ? rule.byDay.map(({ weekday }) => weekday) : [weekdayOf(start)]
+    return weeks % rule.interval === 0 && weekdays.includes(weekdayOf(candidate))
+  }
+  if (rule.freq === FREQUENCY.monthly) {
+    return monthsBetween(start, candidate) % rule.interval === 0 && matchesMonthly(rule, start, candidate)
+  }
+  if (rule.freq === FREQUENCY.yearly) {
+    const month = rule.byMonth.length > 0 ? candidate.month : start.month
+    return (candidate.year - start.year) % rule.interval === 0 && candidate.month === month && candidate.day === start.day
+  }
+  return false
+}
+
+const durationMs = (event: IcsEvent): number => {
+  if (!event.end) return event.start.allDay ? DAY_MS : 0
+  if (event.start.allDay) return (dayNumber(event.end.civil) - dayNumber(event.start.civil)) * DAY_MS
+  return instantOf(event.end.civil, event.end.zone) - instantOf(event.start.civil, event.start.zone)
+}
+
+const startMsOf = (date: IcsDate, viewZone: string): number =>
+  date.allDay ? instantOf(date.civil, viewZone) : instantOf(date.civil, date.zone)
+
+const isBeyondUntil = (rule: Rule, candidate: IcsDate, viewZone: string): boolean => {
+  if (!rule.until) return false
+  if (rule.until.allDay || candidate.allDay) return dayNumber(candidate.civil) > dayNumber(rule.until.civil)
+  return startMsOf(candidate, viewZone) > startMsOf(rule.until, viewZone)
+}
+
+const expandRule = (event: IcsEvent, rule: Rule, lastDay: Civil, viewZone: string): IcsDate[] => {
+  const dates: IcsDate[] = []
+  let matched = 0
+  for (let civil = event.start.civil; dayNumber(civil) <= dayNumber(lastDay); civil = addDays(civil, 1)) {
+    if (!ruleMatches(rule, event.start.civil, civil)) continue
+    const candidate = { ...event.start, civil }
+    if (isBeyondUntil(rule, candidate, viewZone)) break
+    matched += 1
+    if (rule.count !== undefined && matched > rule.count) break
+    dates.push(candidate)
+  }
+  return dates
+}
+
+/**
+ * Every occurrence that overlaps the civil day `today` in `viewZone`. Recurring events are expanded
+ * day by day from their DTSTART (FREQ DAILY, WEEKLY, MONTHLY and YEARLY with INTERVAL, UNTIL, COUNT,
+ * BYDAY, BYMONTHDAY and BYMONTH); a rule beyond that is skipped. EXDATE removes an occurrence, an
+ * event with RECURRENCE-ID replaces it, and a cancelled one is dropped.
+ */
+export const occurrencesOn = (events: IcsEvent[], today: Civil, viewZone: string): Occurrence[] => {
+  const dayStart = instantOf({ ...today, hour: 0, minute: 0, second: 0 }, viewZone)
+  const dayEnd = instantOf({ ...addDays(today, 1), hour: 0, minute: 0, second: 0 }, viewZone)
+  const overridden = new Set(
+    events.flatMap((event) => (event.recurrenceId ? [`${event.uid}@${occurrenceKey(event.recurrenceId)}`] : [])),
+  )
+  const occurrences: Occurrence[] = []
+  for (const event of events) {
+    if (event.status === EVENT_STATUS.cancelled) continue
+    if (event.rule?.unsupported) continue
+    const starts = event.rule && !event.recurrenceId ? expandRule(event, event.rule, today, viewZone) : [event.start]
+    for (const start of starts) {
+      const key = occurrenceKey(event.recurrenceId ?? start)
+      if (!event.recurrenceId && (event.exDates.includes(key) || overridden.has(`${event.uid}@${key}`))) continue
+      const startMs = startMsOf(start, viewZone)
+      const endMs = startMs + durationMs(event)
+      const overlaps = startMs < dayEnd && (endMs > dayStart || (endMs === startMs && startMs >= dayStart))
+      if (overlaps) occurrences.push({ event, key, startMs, endMs })
+    }
+  }
+  return occurrences.sort((a, b) => a.startMs - b.startMs)
+}
+
+const clock = (ms: number, zone: string): string => {
+  const civil = civilOf(ms, zone)
+  return `${String(civil.hour).padStart(2, '0')}:${String(civil.minute).padStart(2, '0')}`
+}
+
+const whenOf = (occurrence: Occurrence, zone: string): string => {
+  if (occurrence.event.start.allDay) return 'all day'
+  if (occurrence.endMs === occurrence.startMs) return clock(occurrence.startMs, zone)
+  return `${clock(occurrence.startMs, zone)}–${clock(occurrence.endMs, zone)}`
+}
+
+/** A short stable id per occurrence: the report line prints it, and a Google UID runs to 60 characters. */
+export const occurrenceId = (uid: string, key: string): string =>
+  new Bun.CryptoHasher('sha1').update(`${uid}@${key}`).digest('hex').slice(0, 12)
+
+/** Google Calendar's day view of `today`, a short link the watcher keeps. */
+const dayUrl =(today: Civil): string =>
+  `https://calendar.google.com/calendar/r/day/${today.year}/${today.month}/${today.day}`
+
+export const toItems = (occurrences: Occurrence[], today: Civil, zone: string): CalendarItem[] =>
+  occurrences.map((occurrence) => {
+    const { event } = occurrence
+    const what = [event.summary || '(no title)', event.location].filter(Boolean).join(' · ')
+    return {
+      id: occurrenceId(event.uid, occurrence.key),
+      title: `${whenOf(occurrence, zone)} ${what}`,
+      url: dayUrl(today),
+      updatedAt: event.lastModified
+        ? new Date(instantOf(event.lastModified.civil, event.lastModified.zone)).toISOString()
+        : '',
+    }
+  })

package/recipes/sources/jira.ts

@@ -12,14 +12,22 @@ const plainText = (node: DocumentNode): string =>
     ? (node.text ?? node.attrs?.text ?? '')
     : (node.content ?? []).map(plainText).join('')
 
+// The watcher shows this line with the exit code; it never carries acli's output.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const acli = async (args: string[]): Promise<unknown> => {
   const child = Bun.spawn(['acli', ...args], { stdout: 'pipe', stderr: 'ignore', signal: AbortSignal.timeout(20_000) })
   const output = await new Response(child.stdout).text()
-  if ((await child.exited) !== 0) process.exit(1)
+  const code = await child.exited
+  const call = `acli ${args.slice(0, 2).join(' ')}`
+  if (code !== 0) fail(`${call} exited ${code}`)
   try {
     return JSON.parse(output)
   } catch {
-    return process.exit(1)
+    return fail(`${call} answered no JSON`)
   }
 }
 

package/recipes/sources/linear.ts

@@ -1,6 +1,12 @@
 // Copy to scripts/sources/linear.ts in your repository; the recipe recipes/linear.md says what to fill in.
+// The watcher shows this line with the exit code; it never carries the token or a URL.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const token = process.env.LINEAR_API_KEY
-if (!token) process.exit(1)
+if (!token) fail('LINEAR_API_KEY not set')
 
 const query = `{ issues(filter: { team: { key: { eq: "ENG" } }, number: { eq: 123 } }) {
   nodes { identifier title url updatedAt comments { nodes { body user { name } } } } } }`
@@ -11,9 +17,9 @@ const response = await fetch('https://<host>/graphql', {
   body: JSON.stringify({ query }),
   signal: AbortSignal.timeout(20_000),
 })
-if (!response.ok) process.exit(1)
+if (!response.ok) fail(`HTTP ${response.status}`)
 const answer = (await response.json()) as { errors?: unknown }
-if (answer.errors) process.exit(1)
+if (answer.errors) fail('GraphQL errors in the answer')
 console.log(JSON.stringify(answer))
 
 export {}

package/recipes/sources/sentry.ts

@@ -1,12 +1,18 @@
 // Copy to scripts/sources/sentry.ts in your repository; the recipe recipes/sentry.md says what to fill in.
+// The watcher shows this line with the exit code; it never carries the token or a URL.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const token = process.env.SENTRY_AUTH_TOKEN
-if (!token) process.exit(1)
+if (!token) fail('SENTRY_AUTH_TOKEN not set')
 
 const response = await fetch(
   'https://<host>/api/0/projects/<org>/<project>/issues/?query=is:unresolved&statsPeriod=24h',
   { headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(20_000) },
 )
-if (!response.ok) process.exit(1)
+if (!response.ok) fail(`HTTP ${response.status}`)
 console.log(JSON.stringify(await response.json()))
 
 export {}

package/recipes/sources.md

@@ -2,7 +2,7 @@
 
 The fields and limits of a `watch.sources` entry, for a source no [recipe](README.md) covers or a field a recipe leaves open.
 
-Source reports are off unless the config lists `watch.sources`. The watcher cannot use the MCP servers of a Claude Code session: their connections and logins (often OAuth in a browser) belong to the session. A source is a command instead, which prints JSON on stdout. It runs without a shell, in the main checkout, with your environment, so its token stays where it is. `/jh-follow` fills one of the [recipes](README.md) for you.
+Source reports are off unless the config lists `watch.sources`. The watcher cannot use the MCP servers of a Claude Code session: their connections and logins (often OAuth in a browser) belong to the session. A source is a command instead, which prints JSON on stdout. It runs without a shell, in the main checkout (a personal source: below), with your environment, so its token stays where it is. `/jh-follow` fills one of the [recipes](README.md) for you.
 
 ```json
 {
@@ -76,9 +76,23 @@ dry run source tickets: ["tickets-cli","search","--query","key in (T-123)","--js
 first run of this source: baseline, nothing reported; later a new or changed entry reports like this:
 === source tickets (search) T-123 Decide the layout · new
   Yes, take variant B.
-watcher state not read or changed; the watcher takes a new source over at its next start
+watcher state not read or changed; a running watcher takes a new source over at its next cycle
 ```
 
-The watcher reads `watch.sources` when it starts: a new or changed source counts from its next start.
+**Keep a personal source.** A source can live in `~/.jackherd/sources.json` instead of the repository: `{ "$schema": "…/schemas/sources.schema.json", "sources": [ … ] }`, entries as above. It runs in every repository where the watcher starts, after the repository's `watch.sources`, unless it carries `"repos": ["owner/name"]` (one to twenty, unique without regard to case): then it runs only where the main checkout's `origin` names one of them, and elsewhere the watcher notes `<name>: not for this repo` (`<name>: no origin` when the checkout has none). `repos` belongs in the personal file only; the repository's config refuses it. `jh watch source <name> --dry-run` of a left-out source prints the note and exits 2 without running anything. On a name clash the repository's source wins and the personal one is skipped with a note. A personal source runs with `~/.jackherd/` as its working directory, so its script is `~/.jackherd/sources/<name>.ts` and its command `["bun", "sources/<name>.ts"]`. `jh watch source <name> --dry-run` finds it too and prints `origin: personal, <path>`; a draft file runs as a repository source, in the main checkout and without the keychain.
+
+**Keep a secret for a source.** `"secrets": ["NAME"]` (up to 10 names, `A-Z`, digits and `_`, starting with a letter) puts those variables into the environment of the source's command, and nowhere else. For a personal source each value comes from the keychain (service `jackherd`), else from the watcher's own environment; a repository source gets them from the watcher's environment only, never from the keychain. A value that is found nowhere fails the run with `secret missing: NAME`, an unreachable keychain with `secret store unavailable`; other sources go on. The script reads the value from `process.env` and never prints it.
+
+```text
+jh secret set NAME      asks for the value hidden, needs a terminal (exit 2 without), never takes it as argument or from stdin
+jh secret list          each name the sources need: set, set (environment), missing, missing (environment only), secret store unavailable
+jh secret delete NAME
+```
+
+**Show entries as content.** `"show": "entries"` opens the source's entries in a herd block of their own under "Your turn", headed by its `label`, instead of the folded row in `Sources`. For a source whose entries are the day's content, such as a calendar; not together with `ticket`.
+
+The watcher and the herd read the repository's config and the personal file again each cycle (about a minute): a new, changed or removed source counts without a restart, a new one runs at once. A changed file that is invalid keeps the previous sources and prints `sources not reloaded: <file>: <reason>`. `deploy`, `feedback`, `previews` and `checks` follow the same way; a change that applies prints `config reloaded: <parts>`, an invalid one keeps every value and prints `config not reloaded: <file>: <reason>`. The board and the language are read when the watcher starts.
+
+**Say why a source failed.** A failing command may print one stdout line `jackherd-reason: <reason>` (a status, a missing variable); the watcher shows the last such line as `exit 1: <reason>`, with the values of the source's `secrets` and URL credentials masked, cut to 160 characters. stderr is never read. Name no token in it.
 
 Three limits stand: the watcher cannot make a command read only, so name only commands that read. A source in `.jackherd/config.json` runs for everyone who starts the watcher in the repository, at the same level of trust as `check.checks` and hooks. The watcher reads the config of the main checkout, never the one of a lane's worktree; a dry run started inside a worktree reads that worktree's config first. And `jh watch source … --dry-run` runs whatever command its draft names, so it never belongs in a permission allowlist.

package/schemas/jackherd.schema.json

@@ -143,6 +143,10 @@
         "lockFile": {
           "type": "string",
           "pattern": "^(?![/-])(?!(?:.*\\/)?\\.\\.(?:\\/|$))[A-Za-z0-9._/-]+$"
+        },
+        "minFreeGb": {
+          "type": "number",
+          "exclusiveMinimum": 0
         }
       },
       "additionalProperties": false
@@ -645,6 +649,15 @@
               "show": {
                 "type": "string",
                 "const": "entries"
+              },
+              "repos": {
+                "minItems": 1,
+                "maxItems": 20,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+                }
               }
             },
             "required": [
@@ -699,6 +712,28 @@
               "type": "integer",
               "minimum": 1,
               "maximum": 9
+            },
+            "standing": {
+              "type": "object",
+              "properties": {
+                "tools": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "pattern": "^mcp__[A-Za-z0-9_-]+__execute_sql$"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "enum": [
+                      "stage"
+                    ]
+                  }
+                }
+              },
+              "required": [
+                "tools"
+              ],
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
@@ -929,6 +964,38 @@
             "maximum": 9007199254740991
           }
         },
+        "openBoxes": {
+          "default": "fail",
+          "type": "string",
+          "enum": [
+            "fail",
+            "warn",
+            "off"
+          ]
+        },
+        "lintPointers": {
+          "type": "object",
+          "properties": {
+            "level": {
+              "default": "warn",
+              "type": "string",
+              "enum": [
+                "warn",
+                "fail",
+                "off"
+              ]
+            },
+            "exclude": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        },
         "looseTests": {
           "default": false,
           "type": "boolean"

package/schemas/sources.schema.json

@@ -126,6 +126,15 @@
           "show": {
             "type": "string",
             "const": "entries"
+          },
+          "repos": {
+            "minItems": 1,
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+            }
           }
         },
         "required": [