jackherd 1.15.1 → 1.16.0

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/schemas/jackherd.schema.json

@@ -633,6 +633,18 @@
                   "type": "string",
                   "minLength": 1
                 }
+              },
+              "secrets": {
+                "maxItems": 10,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[A-Z][A-Z0-9_]*$"
+                }
+              },
+              "show": {
+                "type": "string",
+                "const": "entries"
               }
             },
             "required": [

package/schemas/sources.schema.json

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

package/src/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,

package/src/cli.ts

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

package/src/config/json-schema.ts

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

package/src/config/location.ts

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

package/src/config/personal-sources.ts

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

package/src/config/schema.ts

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

package/src/plans/herd-claim.ts

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