jackherd 1.15.1 → 1.16.0

package/kit/workflow/skills/follow/SKILL.md

@@ -1,36 +1,41 @@
 ---
 name: follow
-description: 'Have the watcher report changes of something outside GitHub (a ticket, an issue, an error, a status page): pick a recipe, check the tool and its login read only, dry-run the source, write it to `watch.sources` after approval. Use when the user asks to follow or be told about such an item, e.g. "/follow PROJ-123".'
+description: 'Have the watcher report changes of something outside GitHub (a ticket, an issue, an error, a status page): pick a recipe, check the tool and its login read only, dry-run the source, write it to the watcher''s sources (personal or repository) after approval. Use when the user asks to follow or be told about such an item, e.g. "/follow PROJ-123".'
 argument-hint: 'What to follow, e.g. a ticket key, an issue or a query'
 ---
 
 If `.claude/project/follow.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
 
-You add one entry to `watch.sources`, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the project's `.jackherd/config.json` in the main checkout, and only after the user approved the entry. Read the recipe index `recipes/README.md` of the installed package first (`"$(dirname "$(readlink -f "$(command -v jh)")")/../recipes/README.md"`), then only the recipe file it names for the chosen service; do not copy a recipe from memory. Where the recipe leaves a field open, the index's section **Rules every recipe follows** decides, and `recipes/sources.md` beside it describes every field and limit of a source.
+You add one entry to the watcher's sources, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the entry's file (step 4: the user's `~/.jackherd/sources.json` or the project's `.jackherd/config.json` in the main checkout), and only after the user approved the entry. Read the recipe index `recipes/README.md` of the installed package first (`"$(dirname "$(readlink -f "$(command -v jh)")")/../recipes/README.md"`), then only the recipe file it names for the chosen service; do not copy a recipe from memory. Where the recipe leaves a field open, the index's section **Rules every recipe follows** decides, and `recipes/sources.md` beside it describes every field and limit of a source.
 
 ## 1. Ask
 
 `AskUserQuestion` in {{kit.responseLanguage}}, only for what the argument and the conversation leave open, each with the recommended option first; at most four questions per call, so more open points go into a second call:
 
+- **Where it lives:** a personal source (`~/.jackherd/sources.json`: runs in every repository of the user, the keychain can hold its secrets; recommended when a personal secret is attached, otherwise second) or a repository source (`watch.sources` of the project: runs for everyone who starts the watcher there, and its `secrets` read only the watcher's environment, never the keychain, so it needs a token from the environment or none).
 - **Service:** the services the recipe index lists, and "another command that prints JSON".
 - **What to follow:** the item the argument names (its comments, recommended) or a query over several items.
 - **Lane:** the lane the reports name, from the board's lanes table, or none.
 - **Ticket:** whether the entries are tickets (`ticket: true`, recommended for an issue tracker or a project board), which the herd shows as a badge beside the plan of their lane: the lane above, or the lane whose name, board row or plan names the ticket's id. A source of comments or messages is no ticket; it shows in the herd's `Sources` block instead (a click opens the entry at `map.url`). The path of the status you find yourself in step 3.
-- **Tone:** for a non-ticket source, the colour of its `Sources` mark while its report is new (`tone`: amber, teal, grey, red, green, blue, magenta); recommended: no `tone`.- **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
+- **Tone:** for a non-ticket source, the colour of its `Sources` mark while its report is new (`tone`: amber, teal, grey, red, green, blue, magenta); recommended: no `tone`.
+- **Show:** for a non-ticket source whose entries are the day's content (a calendar), `show: "entries"` opens them in a block of their own under "Your turn"; otherwise none.
+- **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
 - **Own changes:** ignore the user's own account on that service (`ignoreAuthors`, needs an author in the map), or report everything.
 
 ## 2. Check, read only
 
 - The tool: `command -v <tool>` for the recipe's program (`curl`, the service's CLI, and `bun` for a recipe with a script).
-- The login: the tool's own status command where it has one. For a token in an environment variable only whether it is set: `test -n "$<VARIABLE>" && echo set || echo missing`. Never print, echo or pass on a token's value, and never read a file that holds one.
+- The login: the tool's own status command where it has one. For a token in an environment variable only whether it is set: `test -n "$<VARIABLE>" && echo set || echo missing`. Never print, echo or pass on a token's value, never ask for it, and never read a file that holds one.
 
-Anything missing goes to the user as the command to run themselves (`! <command>`); wait until they did, then check again.
+Anything missing goes to the user as the command to run themselves (`! <command>`; a keychain secret: below, not with `!`); wait until they did, then check again.
+
+**A secret** (a token the script needs) is named in the entry's `secrets` (`["NAME"]`) and never passes through you (the rule above). A repository source does not read the keychain: check its environment variable as above. A personal source's secret goes into the keychain in step 4, after the entry is written: `jh secret list` knows only names an entry already lists.
 
 ## 3. Fill and dry-run
 
 Before filling, read the help of the installed CLI version for every command the recipe calls (`acli jira workitem search --help` and `workitem view --help`, `gh issue list --help`) and confirm that the fields and options the entry needs exist there. Read the provider's web documentation only when the help leaves it open or no recipe fits. A recipe is a starting point; the installed version decides.
 
-Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors`, `ticket` and `tone` where chosen, and a short `label` (e.g. `Error log · Checkout`; it prefixes the source's `Waiting for you` rows). For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it, from the recipe's script under `recipes/sources/`, to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. Script and direct command follow the index's **Rules every recipe follows**.
+Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors`, `ticket` and `tone` where chosen, and a short `label` (e.g. `Error log · Checkout`; it prefixes the source's `Waiting for you` rows). For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it, from the recipe's script under `recipes/sources/`, to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]` (a personal source runs in `~/.jackherd/`: `["bun", "sources/<name>.ts"]`). Script and direct command follow the index's **Rules every recipe follows**.
 
 Write the entry as one JSON object to a draft file in the scratchpad and run, from the main checkout:
 
@@ -38,12 +43,15 @@ Write the entry as one JSON object to a draft file in the scratchpad and run, fr
 jh watch source <draft.json> --dry-run
 ```
 
-It runs the command once and shows the entries and the report the watcher would print, without touching the watcher's state. Exit code 1 means the run failed or a `map` field is empty in every entry (`map.<field>: in … entries empty (<path>)`): never write such an entry, correct the path or drop the field. When the run fails or the entries look wrong, run it again with `--raw` to see the command's output, correct `items` or a path of `map`, and try again; after two failed corrections, show the user the reason and the output's first lines and ask how to go on. Show the user the dry run's list and report, not the raw output.
+It runs the command once and shows the entries and the report the watcher would print, without touching the watcher's state. A draft runs as a repository source: in the main checkout, without the keychain. A personal entry with `secrets` or a script under `sources/` cannot pass there; skip its draft run, show the entry and the recipe's sample output, and dry-run it by name in step 4. Exit code 1 means the run failed or a `map` field is empty in every entry (`map.<field>: in … entries empty (<path>)`): never write such an entry, correct the path or drop the field. When the run fails or the entries look wrong, run it again with `--raw` to see the command's output, correct `items` or a path of `map`, and try again; after two failed corrections, show the user the reason and the output's first lines and ask how to go on. Show the user the dry run's list and report, not the raw output.
 
 ## 4. Write after approval
 
-Ask through `AskUserQuestion`: write the entry (recommended), change it, or drop it. Say in the question that the source runs for everyone who starts the watcher in this repository, and that the watcher cannot keep a command from writing, so the command only reads.
+Ask through `AskUserQuestion`: write the entry (recommended), change it, or drop it. Say in the question which file it goes to and that the watcher cannot keep a command from writing, so the command only reads; for a repository source add that it runs for everyone who starts the watcher in this repository.
+
+On approval write exactly one of these files, and a script from step 3 under the path the entry names:
 
-On approval add the entry to `watch.sources` in `.jackherd/config.json` of the main checkout (create the array if missing), and a script from step 3 under the path the entry names. Then run `jh config`, which fails on an invalid config, and `jh watch source <name> --dry-run` once more against the written entry.
+- **Personal:** add the entry to `sources` in `~/.jackherd/sources.json`; create the file as `{ "$schema": "<installed package>/schemas/sources.schema.json", "sources": [] }` if missing (the package directory is the one the recipe path above resolves to, minus `/recipes/README.md`). The script goes to `~/.jackherd/sources/<name>.ts`. A repository source of the same `name` wins over it, so pick a name the project does not use. For each name in `secrets`, ask the user to run `jh secret set <NAME>` in a terminal of their own (a separate pane; it asks hidden and refuses without a terminal), wait, then check only `jh secret list`: `set` is fine, `missing` means they still have to, `set (environment)` means the watcher's environment must carry it too, `secret store unavailable` means it can come only from that environment. Then run `jh watch source <name> --dry-run`; it prints `origin: personal`. A failure here is corrected in the written entry as in step 3.
+- **Repository:** add the entry to `watch.sources` in `.jackherd/config.json` of the main checkout (create the array if missing). Then run `jh config`, which fails on an invalid config, and `jh watch source <name> --dry-run` once more.
 
-End with one line: the watcher takes the source over at its next start, so a running watcher (the coordinator's stream) has to be started again. The new file and the changed config are part of the repository and follow its commit rules.
+End with one line: a running watcher and the herd take the source over at their next cycle (about a minute); a file that is invalid then keeps the previous sources and prints `sources not reloaded`. A repository entry and its script are part of the repository and follow its commit rules; the personal file is not.

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -84,6 +84,8 @@ otherwise it runs in a fitting lane, as its next phase or as a subagent there (`
 table are met and step 1 finds nothing. One line to the user afterwards; commit, push, PR and merge
 stay approval-bound (§ 5, § 6).
 
+**A pull request of the lane that only waits for its approval or its merge holds the commit, not the next phase.** While only the approval waits there is no commit yet: the next phase goes on in the same worktree, and the commit stages only that PR's files. A round or phase the plan starts "after the PR" begins at once, on a branch over the PR's branch, and after the squash merge moves onto the base branch with `git rebase --onto origin/{{kit.baseBranch}} <old PR head>` (§ 6). Waiting stays for a PR of another lane that shares a write path, for a migration and for a release.
+
 When the user wants a plan's lanes merged without a question for a while: § 5, **Standing approval**.
 
 0. **Plan commit as the base**, when § 0 found the board or a plan missing on
@@ -250,7 +252,7 @@ On wake-up:
 | `blocked` | Read the screen (`--source detection`, or zoom the pane when cut off). A question is vetted (below, **Settled questions stay in the lane**): one the plan or a rule settles you answer in the lane, an open decision goes to the user via `AskUserQuestion`. You never hand the lane's pane to the user. A question dialog in a lane (not a permission dialog) is a gap in the lane prompt (§ 1): send it the text-block rule and the answer by prompt. A permission dialog for a step on the list in § 5 you confirm, after checking the cursor sits on the one-time option; anything else goes to the user. Dim text in the input line is a suggestion, not input (`--format ansi` shows `\e[2m`); in a multi-select dialog `space` toggles an option, `enter` moves on. The watcher prints a duty line for each blocked lane; it is done when the lane has its answer or the user has the question |
 | `working` with `questions: <n>` | The lane changed the questions of its report while its subagents run. Read `report <path>` and close each new question as the `done` / `idle` row does (`jh settled`, or `AskUserQuestion` with the answer sent on by `herdr agent prompt`). No diff check and no next phase: the lane keeps working |
 | `main checkout on <branch>, not …` | § 0, **The main checkout stays on `{{kit.baseBranch}}`** |
-| `done` / `idle` | Read the report the watcher shows (`report <path>` and its first lines, or the screen); read further only where that is not enough. Check the diff against the `{{kit.heading.writes}}` set (`git -C <worktree> diff --stat <base>...HEAD`, with the ref the lane branched from in § 2 step 2 until it has rebased after the documentation PR's merge) and that checks are quoted with numbers, not claimed. Every blocking question in the report is closed in the same wake-up, also one under open points, one without its mark and also when the `questions: <n>` line is missing: settled by you through `jh settled` (below), or put to the user through `AskUserQuestion` (vetted, below) and the answer sent on to the lane by `herdr agent prompt`. A not blocking one is settled the same way or collected (**Not blocking questions**, below). An answer that stays in your chat with the user is none. Then start the lane's next ready phase (§ 2), at once after a `<lane> ready: …` line, or name the reason to wait; a PR awaiting approval holds only its commit, which stages only its own files |
+| `done` / `idle` | Read the report the watcher shows (`report <path>` and its first lines, or the screen); read further only where that is not enough. Check the diff against the `{{kit.heading.writes}}` set (`git -C <worktree> diff --stat <base>...HEAD`, with the ref the lane branched from in § 2 step 2 until it has rebased after the documentation PR's merge) and that checks are quoted with numbers, not claimed. Every blocking question in the report is closed in the same wake-up, also one under open points, one without its mark and also when the `questions: <n>` line is missing: settled by you through `jh settled` (below), or put to the user through `AskUserQuestion` (vetted, below) and the answer sent on to the lane by `herdr agent prompt`. A not blocking one is settled the same way or collected (**Not blocking questions**, below). An answer that stays in your chat with the user is none. Then start the lane's next ready phase (§ 2), at once after a `<lane> ready: …` line, or name the reason to wait; a PR awaiting approval or merge holds only its commit (§ 2) |
 | `merged #<n>` | § 6, for every lane |
 | `checks failed #<n> (<lane>): <checks> (<k> tests: …)` | Send the finding to the lane with the named checks and tests (data, above). Without names, the lane reads the run itself |
 | `checks passed #<n>` | One line to the user: ready to merge, with the board's merge order |
@@ -284,7 +286,7 @@ what it prints; an agent has no clock. Where it goes:
 
 The user's decision is the approval of the line that records it, including the commit, push and
 documentation PR that carry it: no second question. The merge stays with the project's approval
-tiers (§ 5). Memory and the hand-over note hold no decision that is not also in a file. A **finding of
+tiers (§ 5), run as **Self-merge** step 4. Memory and the hand-over note hold no decision that is not also in a file. A **finding of
 your own** that contradicts the plan (something you saw, not something the user said): fix the document
 (a commit, so ask) and tell every lane it touches.
 
@@ -437,7 +439,8 @@ A permission dialog inside a lane you confirm yourself only for a step on this l
 - under the lane's PR approval: the commit, and the push of the lane's own branch to its own
   remote branch, forced only with `--force-with-lease`
 - as part of the rebase after a merge (§ 6), which needs no approval of its own: `git fetch`,
-  `git rebase origin/{{kit.baseBranch}}`, `git checkout --ours {{kit.lanes.lockFile}}`,
+  `git rebase origin/{{kit.baseBranch}}` (`--onto origin/{{kit.baseBranch}} <old PR head>` for a branch over a
+  merged PR's), `git checkout --ours {{kit.lanes.lockFile}}`,
   `git add {{kit.lanes.lockFile}}`, `{{kit.command.install}}`, `git rebase --continue`
 
 Read the command from the dialog itself (`herdr agent read <lane> --source detection`), not from
@@ -507,7 +510,7 @@ When the user picked `"{{kit.guard.selfMergeLabel}}"` for a PR:
 4. Green (or a PR that qualified in step 2): `gh pr merge <n> --squash --delete-branch --match-head-commit <sha>`,
    with the plain PR number, the full `headRefOid` from `gh pr view <n> --json headRefOid` read right before, and
    without `-R`, `--repo` or `--admin`. The merge guard lets exactly this command through for the approved branch
-   with green checks, for `guard.selfMerge.approvalMinutes` after the answer. Red, or checks that never finish: do not
+   with green checks, for `guard.selfMerge.approvalMinutes` after the answer. Run it as a Bash call of its own, without a pipe, `;` or `&&`, and read the result afterwards with `gh pr view <n>`: the guard checks a merge against approval and checks only when it is the sole command of the call, and asks otherwise. Red, or checks that never finish: do not
    merge, report to the user with the failing check and the lane's next step.
 5. When the guard asks anyway (the approval lapsed, the branch differs, the command carries an
    option it does not cover), the dialog is the user's. Do not confirm it for them and do not look
@@ -545,7 +548,7 @@ For a PR the user approved (step 2) whose lane works on a plan under a standing
 1. A PR behind the base branch is rebased first (§ 6, under the PR's approval), so its checks run
    against the current base.
 2. Turn a draft ready as in **Self-merge** step 1, then wait for the checks as in its step 3.
-3. Green: the same command as **Self-merge** step 4, with the `<sha>` read right before. The merge
+3. Green: the same command as **Self-merge** step 4, run the same way, with the `<sha>` read right before. The merge
    guard lets it through only before the approval's end, with every check green, GitHub able to merge
    it and no workflow, migration, env file or file of the guards in it; otherwise it asks, and that dialog is the user's
    (**Self-merge** step 5).
@@ -563,7 +566,7 @@ For a PR the user approved (step 2) whose lane works on a plan under a standing
   No overlap, no run; an overlap runs the checks of the touched package roots; whenever in doubt, a lock-file
   conflict or a change to the root `package.json` among them, all of them run. A `{{kit.lanes.lockFile}}` conflict is never resolved by hand: take the base branch's
   (`git checkout --ours {{kit.lanes.lockFile}}` during a rebase), run `{{kit.command.install}}`, continue.
-- Merge order is the board's. A lane ready early waits; say so.
+- Merge order is the board's. A PR ready early waits for its turn to merge, its lane goes on (§ 2); say so.
 - **The documentation PR of § 2 step 0 merges first**, before any lane PR that started from it. After its
   merge, the copies in the main checkout and its branch are cleaned up as in
   [`references/plan-commit.md`](references/plan-commit.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "keywords": [
     "claude-code",
     "coding-agents",
@@ -52,6 +52,7 @@
     "!assets/icons/build.ts",
     "!assets/branding/outline.ts",
     "recipes",
+    "!recipes/**/*.test.ts",
     "README.md",
     "INSTALL.md",
     "CHANGELOG.md",

package/recipes/README.md

@@ -10,13 +10,14 @@ Each recipe is one `watch.sources` entry for the jackherd watcher: put in your k
 | GitHub issues | [github-issues.md](github-issues.md) | `gh auth login` | none |
 | GitHub Projects, as tickets | [github-projects.md](github-projects.md) | `gh auth refresh -s project` | none |
 | Sentry | [sentry.md](sentry.md) | `SENTRY_AUTH_TOKEN` | [sources/sentry.ts](sources/sentry.ts) |
+| Google Calendar, today's appointments | [google-calendar.md](google-calendar.md) | secret iCal address in `GOOGLE_CALENDAR_ICS_URL` | [sources/google-calendar-today.ts](sources/google-calendar-today.ts) |
 | A status page | [status-page.md](status-page.md) | none, public API | none |
 
 ## Rules every recipe follows
 
-- **A token never goes into an argument:** an argument shows in the process list. Where a tool keeps its own login, it is used; where a token sits in an environment variable, a small TypeScript script run by Bun (which runs wherever `jh` does) puts it from `process.env` straight into the request header.
+- **A token never goes into an argument:** an argument shows in the process list. Where a tool keeps its own login, it is used; where a token sits in an environment variable, a small TypeScript script run by Bun (which runs wherever `jh` does) puts it from `process.env` straight into the request header. The token reaches the script through the entry's `secrets` (the keychain, for a personal source only; see [sources.md](sources.md)) or through the watcher's environment; either way the script reads `process.env`.
 - **A script prints one JSON value on stdout and nothing else.**
 - **A script fails with an exit code**, never with an empty answer the watcher would take for a source with nothing new, and it prints neither the token nor the body of a failed answer. A 200 that carries an `errors` list, as GraphQL answers, is a failure too. Every request and every tool call is bounded with `AbortSignal.timeout(20_000)`, well under the 30 seconds a source may run.
-- **The scripts are files of their own** under [`sources/`](sources/). Copy one to `scripts/sources/<name>.ts` in your repository, the path the entry's `command` names. The closing `export {}` makes the file a module, so the type check accepts top-level `await` and the names do not clash between scripts.
+- **The scripts are files of their own** under [`sources/`](sources/). Copy one to `scripts/sources/<name>.ts` in your repository (a personal source: `~/.jackherd/sources/<name>.ts`), the path the entry's `command` names. The closing `export {}` makes the file a module, so the type check accepts top-level `await` and the names do not clash between scripts.
 - **A recipe that needs no script** (`gh …`, `curl` on a public page, `curl --netrc`) stays a direct command.
 - **`bun` as the first word, never a path to it.** The watcher starts a source without a shell and reads `bun` to mean the Bun that runs the watcher itself, so the entry needs no absolute path, which would differ from machine to machine, even when Bun is not on the `PATH` (installed in `~/.bun/bin` only, say).

package/recipes/google-calendar.md

@@ -0,0 +1,30 @@
+# Google Calendar, today's appointments
+
+Your day, from the calendars you already keep in Google Calendar, opened in the herd under "Your turn". No Google login and no API project: Google gives each calendar a secret address in the iCalendar format, and that address is the credential.
+
+**Secret address:** in Google Calendar, open the settings of a calendar, section "Integrate calendar", and copy "Secret address in iCal format". Anyone who has the address can read the calendar, so it never goes into the entry, into a repository or into an argument. Store it in the keychain (the command asks hidden and needs a terminal):
+
+```
+jh secret set GOOGLE_CALENDAR_ICS_URL
+jh secret set GOOGLE_CALENDAR_ICS_URL_2    # a second calendar, and so on
+```
+
+**Script:** the day's appointments are a personal matter, so this is a personal source. Copy both [sources/google-calendar.ts](sources/google-calendar.ts) (the iCalendar reader) and [sources/google-calendar-today.ts](sources/google-calendar-today.ts) to `~/.jackherd/sources/`. The script reads the addresses from `GOOGLE_CALENDAR_ICS_URL`, `GOOGLE_CALENDAR_ICS_URL_2`, … and shows the day in the time zone of the machine. It expands daily, weekly, monthly and yearly series with `INTERVAL`, `UNTIL`, `COUNT`, `BYDAY`, `BYMONTHDAY` and `BYMONTH`, honours moved and cancelled occurrences, and skips a series it cannot expand. One calendar that cannot be read fails the whole run, without printing its address; an appointment with a date that cannot be read is skipped on its own.
+
+**Entry:** in `~/.jackherd/sources.json`, under `sources`. List in `secrets` exactly the names you stored; a name that is found nowhere fails the run.
+
+```json
+{
+  "name": "calendar",
+  "label": "Today",
+  "every": 15,
+  "command": ["bun", "sources/google-calendar-today.ts"],
+  "secrets": ["GOOGLE_CALENDAR_ICS_URL"],
+  "show": "entries",
+  "map": { "id": ".id", "updatedAt": ".updatedAt", "title": ".title", "url": ".url" }
+}
+```
+
+**Dry run:** a draft outside `~/.jackherd/sources.json` runs without the keychain. Once the entry is in the file and the secrets are stored, `jh watch source calendar --dry-run` runs it by name, with the keychain, and lists today's appointments.
+
+**Limits:** one entry per occurrence, so a moved or renamed appointment reports as a change and a new day brings its appointments in as new. Google refreshes the iCal feed with a delay of some minutes up to hours. The secret address stays valid until you reset it in the calendar settings; reset it if it leaks.

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

@@ -0,0 +1,32 @@
+// 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
+
+const addresses = addressesOf(process.env)
+if (addresses.length === 0) process.exit(1)
+
+// 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) process.exit(1)
+
+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()
+        : '',
+    }
+  })