jackherd 1.15.2 → 1.16.0

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.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,21 @@ 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`. 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>`. The rest of the config is read when the watcher starts.
 
 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/src/check/skill-budget-defaults.ts

@@ -16,7 +16,10 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/devops/SKILL.md': 321,
   '.claude/skills/diagnose/SKILL.md': 1521,
   '.claude/skills/diagnose/references/feedback-loops.md': 636,
-  '.claude/skills/follow/SKILL.md': 1100,
+  // Personal sources: where the source lives, the secret step that keeps the value out of the agent, the personal
+  // file and its script path, what a reload prints (+295); skill-review: a personal source stores its secret and is
+  // dry-run by name after the entry is written, since a draft runs without the keychain (+103).
+  '.claude/skills/follow/SKILL.md': 1498,
   '.claude/skills/grill/SKILL.md': 685,
   '.claude/skills/implement/SKILL.md': 2190,
   // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
@@ -27,7 +30,10 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   // Cross-check: measured in a repository whose stack nothing detects, every unset command renders as a note (+7).
   // Ready phase: the `done` / `idle` row names the watcher's mandatory `ready:` line (+20).
   // Drafts until the merge: § 5 step 5 opens a draft and readies it, Self-merge step 3 waits for the runs after it (+100).
-  '.claude/skills/orchestrate/SKILL.md': 8230,
+  // Ready round: a PR of the lane waiting for approval or merge holds only the commit; the self-merge command runs
+  // alone, so the guard can check it (+132, the longest rendering of the kit's renderings); skill-review: the commit
+  // of a PR awaiting approval stages only its files, a branch over a squash-merged PR moves with `--onto` (+51).
+  '.claude/skills/orchestrate/SKILL.md': 8413,
   // skill-review: the copy is taken after a mirror, and rejecting together with a remark is a remark (+36).
   // Cross-check: an adopted plan also gets short names and a no-review-gate line, which `jh check` asks of a new
   // plan; the proof became a word diff, since a short name goes into an existing line (+74); skill-review: the
@@ -55,8 +61,9 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   // Any language: step 3 points to proposing the missing commands from the CI; the proposal itself is a reference.
   '.claude/skills/start/SKILL.md': 630,
   '.claude/skills/uncle-bob/SKILL.md': 466,
-  // P33 and open up: grows with the skill above.
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8880,
+  // P33 and open up: grows with the skill above (+132 for the ready round and the lone merge call); measured with
+  // this repository's supplement after the skill-review fixes (+153).
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 9165,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,