jackherd 1.15.1 → 1.15.2

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)))
 }

package/src/plans/settings.ts

@@ -5,6 +5,8 @@ import { PROJECT_CONFIG_PATH } from '../config/location'
 import { readConfig } from '../config/read-config'
 import type { ToneName } from '../config/tones'
 import type { TicketSource } from '../watch/plan-badges'
+import type { SourceShow } from '../watch/sources'
+import { type WatchedSource, watchedSourceOf } from '../watch/watched-source'
 
 export const CONFIG_PATH = PROJECT_CONFIG_PATH
 
@@ -20,14 +22,29 @@ export type PlansSettings = Pick<
   context: JackherdConfig['plans']['context']
   /** The `watch.sources` marked `ticket`, whose entries the view shows as badges. */
   ticketSources: TicketSource[]
-  /** The other `watch.sources` by name, with the tone each names for a new report; the herd lists them in a block of their own. */
-  herdSources: { name: string; tone: ToneName | null }[]
+  /**
+   * The other `watch.sources` by name, with the tone each names for a new report and, when set, how it shows its
+   * entries; the herd lists them in a block of their own.
+   */
+  herdSources: { name: string; tone: ToneName | null; show?: SourceShow }[]
   /** By source name: what the herd puts before a row of "Your turn" that came from the source, its `label` or else its name. */
   sourceLabels: Record<string, string>
   /** The tone of each role in the herd. */
   tones: JackherdConfig['plans']['tones']
 }
 
+/** What the herd draws of the watcher's sources: from the watcher's state when it keeps them, else from the config. */
+export type HerdSourceSettings = Pick<PlansSettings, 'ticketSources' | 'herdSources' | 'sourceLabels'>
+
+/** The herd's view of `sources`, in their order: the tickets, the others with their tone and `show`, every label. */
+export const herdSourceSettingsOf = (sources: readonly WatchedSource[]): HerdSourceSettings => ({
+  ticketSources: sources.flatMap(({ name, lane, ticket }) => (ticket ? [{ name, lane }] : [])),
+  herdSources: sources.flatMap(({ name, ticket, tone, show }) =>
+    ticket ? [] : [{ name, tone, ...(show === null ? {} : { show }) }],
+  ),
+  sourceLabels: Object.fromEntries(sources.map(({ name, label }) => [name, label ?? name])),
+})
+
 /** The locale of the times the herd writes (the refresh error, the last fetch): English, with a 24-hour clock. */
 export const CLOCK_LOCALE = 'en-GB'
 
@@ -45,11 +62,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   shimmer: config.plans.shimmer,
   linkKinds: config.plans.linkKinds,
   context: config.plans.context,
-  ticketSources: config.watch.sources.flatMap(({ name, lane, ticket }) =>
-    ticket ? [{ name, lane: lane ?? null }] : [],
-  ),
-  herdSources: config.watch.sources.flatMap(({ name, ticket, tone }) => (ticket ? [] : [{ name, tone: tone ?? null }])),
-  sourceLabels: Object.fromEntries(config.watch.sources.map(({ name, label }) => [name, label ?? name])),
+  ...herdSourceSettingsOf(config.watch.sources.map(watchedSourceOf)),
   tones: config.plans.tones,
 })
 

package/src/plans/snapshot.ts

@@ -23,7 +23,7 @@ import { isRestingAgent } from '../terminal/types'
 import { laneReportPath, readLaneReport } from '../watch/lane-report-file'
 import { restNote } from '../watch/lane-rest'
 import type { SourceTicket, WatchBadges, WatchHealth } from '../watch/plan-badges'
-import { readWatchReading } from '../watch/plan-badges-read'
+import { readWatchReading, type SourcedWatchReading } from '../watch/plan-badges-read'
 import type { SourceStatus } from '../watch/source-statuses'
 import { assignSignals, laneOfDirectory, type UnplannedTask } from './active-tasks'
 import { activityLineOf, type LaneSubagents } from './activity-read'
@@ -65,7 +65,7 @@ import { markStale, type PlannedPlan, plannedPlans } from './planned'
 import type { PullRequest } from './pull-requests'
 import type { ReadCache } from './read-cache'
 import { type SentChip, sentChipsByLane } from './sent-files'
-import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from './settings'
+import { baseRefOf, boardRepoPathOf, type HerdSourceSettings, type PlansSettings, worktreeOf } from './settings'
 import { signalledTitle } from './signalled-phase'
 import { readAllSignalsSliced } from './signals-read'
 import { createSliceGate, type SliceGate } from './slice-gate'
@@ -194,7 +194,7 @@ type LaneSet = { lanes: SprintLane[]; unlisted: UnlistedLane[]; sources: LaneSou
 
 /** What a lane's view is decorated with after it was read. */
 type Decorations = {
-  reading: ReturnType<typeof readWatchReading> | null
+  reading: SourcedWatchReading | null
   phaseModels: readonly PhaseModelRecord[]
   sprintDirectory: string
   sentChips: ReadonlyMap<string | null, SentChip[]>
@@ -638,7 +638,7 @@ const decoratedViews = (
 /** Each source with the tone and the label its config gives it. */
 const withSourceStyle = (
   statuses: readonly SourceStatus[],
-  { herdSources, sourceLabels }: Pick<PlansSettings, 'herdSources' | 'sourceLabels'>,
+  { herdSources, sourceLabels }: HerdSourceSettings,
 ): HerdSource[] =>
   statuses.map((status) => {
     const label = sourceLabels[status.name]
@@ -646,6 +646,24 @@ const withSourceStyle = (
     return { ...status, tone, ...(label === undefined ? {} : { label }) }
   })
 
+/**
+ * The watcher's reading and the sources the view draws: those the watcher's state names, else the config's. The
+ * state is read every time, so a source the watcher took up since the herd started shows; the reading is null while
+ * the view follows no source and no pull request.
+ */
+const watchReadingOf = (
+  root: string,
+  now: number,
+  fallback: HerdSourceSettings,
+  results: readonly LaneResult[],
+): { reading: SourcedWatchReading | null; sourceSettings: HerdSourceSettings } => {
+  const read = readWatchReading(root, now, fallback)
+  const { ticketSources, herdSources } = read.sourceSettings
+  const watched =
+    ticketSources.length > 0 || herdSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
+  return { reading: watched ? read : null, sourceSettings: read.sourceSettings }
+}
+
 /**
  * The open phases no lane with an agent leads, a plan marked stale by its last change at `baseCommit`; none while the
  * view shows one lane.
@@ -712,25 +730,14 @@ export const loadSnapshot = async (
   const { parsed } = laneSet.sources
   const listedPlans = await readListedPlans(source, base, sprintDirectory, markdown, fallbacks)
   const documentsPlans = Object.assign({}, listedPlans, ...results.map((result) => result.texts))
-  const { ticketSources, herdSources } = settings
-  const watched =
-    ticketSources.length > 0 || herdSources.length > 0 || results.some(({ view }) => view.pullRequests.length > 0)
   await gate.pass()
-  const reading = watched
-    ? readWatchReading(
-        root,
-        now,
-        ticketSources,
-        undefined,
-        undefined,
-        herdSources.map(({ name }) => name),
-      )
-    : null
+  const { reading, sourceSettings } = watchReadingOf(root, now, settings, results)
+  const { ticketSources } = sourceSettings
   await gate.pass()
   const waitingRecords = readWaitingRecords(root)
   const waiting = withSourcePrefix(
     waitingItemsOf(liveBoard, settings.planLanguage, waitingRecords, now),
-    settings.sourceLabels,
+    sourceSettings.sourceLabels,
   )
   const sentChips = sentChipsByLane(waitingRecords.sent, worktrees, now)
   const notice = fallbacks.length > 0 ? fallbackNotice(fallbacks, baseRef, refExists(root, baseRef)) : null
@@ -782,7 +789,7 @@ export const loadSnapshot = async (
     waiting,
     groomedDays: groomedDaysAgo(liveBoard, settings.planLanguage, new Date(now)),
     yourTurn: yourTurnOfBoard(liveBoard, settings.planLanguage, waiting, now),
-    ...(reading?.sources ? { sourceBlock: { sources: withSourceStyle(reading.sources, settings), now } } : {}),
+    ...(reading?.sources ? { sourceBlock: { sources: withSourceStyle(reading.sources, sourceSettings), now } } : {}),
     tones: settings.tones,
     ...(coordinator ? { coordinator: coordinator.view } : {}),
     unplaced: unplacedOf(unplacedSources, laneSet.lanes, Boolean(options.lane)),

package/src/secrets/command.ts

@@ -0,0 +1,163 @@
+import { configuredSources } from '../config/personal-sources'
+import { errorText } from '../plans/error-text'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { CLI_NAME } from '../version/release'
+import type { SourceSettings } from '../watch/sources'
+import type { Environment } from './environment'
+import { hiddenInputStep } from './hidden-input'
+import { environmentOnlyStatusOf, requiredSecrets, secretListing, secretStatusOf } from './listing'
+import { parseSecretArgs, SECRET_ACTION, SECRET_USAGE } from './options'
+import { SECRET_LOOKUP, SECRET_SERVICE, SECRET_WRITE, type SecretStore, secretStore } from './store'
+
+/** What `jh secret` reaches outside itself, so a test runs it against stubs and never against the real keychain. */
+export type SecretPorts = {
+  store: SecretStore
+  /** Whether stdin is a terminal: `set` reads from one only. */
+  isTerminal: () => boolean
+  /** The value typed after `prompt`, hidden; null when cancelled. */
+  readHidden: (prompt: string) => Promise<string | null>
+  /** The sources of the repository and the personal file, with the notes of their merge. */
+  sources: () => { sources: SourceSettings[]; notes: string[] }
+  environment: Environment
+  out: (line: string) => void
+  err: (line: string) => void
+}
+
+/** Exit code of `set` without a terminal, apart from 1 for a wrong command line or a failed write. */
+export const NO_TERMINAL_EXIT = 2
+
+const ENDING_SIGNALS = ['SIGTERM', 'SIGHUP'] as const
+
+/** Exit code after a signal ended the hidden input: 128 + SIGINT, as a cancel. */
+const SIGNAL_EXIT = 130
+
+const NO_TERMINAL = `${CLI_NAME} secret set reads the value from a terminal only, never from a pipe: run it in a terminal of your own`
+
+/**
+ * Reads one hidden value from the terminal: raw mode, nothing echoed, each chunk applied by `hiddenInputStep`. The
+ * terminal is given back on every end, the process's `exit` included.
+ */
+const readHiddenFromTerminal = (prompt: string): Promise<string | null> =>
+  new Promise((resolve) => {
+    const stdin = process.stdin
+    let typed = ''
+    const restore = () => {
+      stdin.off('data', onData)
+      stdin.off('error', onError)
+      process.off('exit', restore)
+      for (const signal of ENDING_SIGNALS) process.off(signal, onSignal)
+      if (stdin.isTTY) stdin.setRawMode(false)
+      stdin.pause()
+    }
+    // A closed pane or a kill ends the process without `exit`: give the terminal back first.
+    const onSignal = () => {
+      restore()
+      process.exit(SIGNAL_EXIT)
+    }
+    // A terminal that goes away (EIO) ends the input as cancelled instead of leaving it open.
+    const onError = () => {
+      restore()
+      resolve(null)
+    }
+    const onData = (chunk: Buffer | string) => {
+      const step = hiddenInputStep(typed, chunk.toString())
+      if (step.kind === 'typing') {
+        typed = step.value
+        return
+      }
+      restore()
+      process.stderr.write('\n')
+      resolve(step.kind === 'done' ? step.value : null)
+    }
+    process.stderr.write(prompt)
+    process.on('exit', restore)
+    for (const signal of ENDING_SIGNALS) process.once(signal, onSignal)
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.on('data', onData)
+    stdin.on('error', onError)
+  })
+
+const terminalPorts = (): SecretPorts => ({
+  store: secretStore(),
+  isTerminal: () => process.stdin.isTTY === true,
+  readHidden: readHiddenFromTerminal,
+  sources: () => configuredSources([worktreeRoot(process.cwd()), mainCheckout(process.cwd())]),
+  environment: process.env,
+  out: (line) => console.log(line),
+  err: (line) => console.error(line),
+})
+
+const setSecret = async (name: string, ports: SecretPorts): Promise<number> => {
+  if (!ports.isTerminal()) {
+    ports.err(NO_TERMINAL)
+    return NO_TERMINAL_EXIT
+  }
+  const value = await ports.readHidden(`${name} (hidden, Enter stores, Ctrl-C cancels): `)
+  if (value === null || value === '') {
+    ports.err(value === null ? 'cancelled, nothing stored' : 'empty value, nothing stored')
+    return 1
+  }
+  if ((await ports.store.set(name, value)) === SECRET_WRITE.unavailable) {
+    ports.err('secret store unavailable, nothing stored')
+    return 1
+  }
+  ports.out(`stored ${name} in the keychain (service ${SECRET_SERVICE})`)
+  return 0
+}
+
+const listSecrets = async (ports: SecretPorts): Promise<number> => {
+  const { sources, notes } = ports.sources()
+  for (const note of notes) ports.err(note)
+  const required = requiredSecrets(sources)
+  const lookups = await Promise.all(required.map(({ name, keychain }) => (keychain ? ports.store.get(name) : null)))
+  const rows = required.map((secret, index) => {
+    const lookup = lookups[index] ?? { kind: SECRET_LOOKUP.absent }
+    const status = secret.keychain
+      ? secretStatusOf(secret.name, lookup, ports.environment)
+      : environmentOnlyStatusOf(secret.name, ports.environment)
+    return { ...secret, status }
+  })
+  for (const line of secretListing(rows)) ports.out(line)
+  return 0
+}
+
+const deleteSecret = async (name: string, ports: SecretPorts): Promise<number> => {
+  const deleted = await ports.store.delete(name)
+  if (deleted === SECRET_WRITE.unavailable) {
+    ports.err('secret store unavailable, nothing deleted')
+    return 1
+  }
+  ports.out(deleted === SECRET_WRITE.done ? `deleted ${name}` : `${name} was not set`)
+  return 0
+}
+
+/**
+ * `jh secret set <NAME> | list | delete <NAME>`: the keychain entries (service `jackherd`) the sources' `secrets`
+ * name. `set` asks for the value hidden in a terminal and exits 2 without one, never reading a pipe; `list` prints
+ * the names the sources need with their status and never a value. Exit 0, 1 on a wrong command line or a keychain
+ * without an answer.
+ */
+export const run = async (args: string[], ports: SecretPorts = terminalPorts()): Promise<number> => {
+  const request = parseSecretArgs(args)
+  if (request.kind === 'help') {
+    if (args.length === 0) {
+      ports.err(SECRET_USAGE)
+      return 1
+    }
+    ports.out(SECRET_USAGE)
+    return 0
+  }
+  if (request.kind === 'error') {
+    ports.err(`${request.message}\n${SECRET_USAGE}`)
+    return 1
+  }
+  try {
+    if (request.kind === SECRET_ACTION.set) return await setSecret(request.name, ports)
+    if (request.kind === SECRET_ACTION.delete) return await deleteSecret(request.name, ports)
+    return await listSecrets(ports)
+  } catch (error) {
+    ports.err(errorText(error))
+    return 1
+  }
+}

package/src/secrets/environment.ts

@@ -0,0 +1,45 @@
+import { SECRET_LOOKUP, type SecretLookup, type SecretLookupFn } from './store'
+
+/** Environment variables as a process sees them; `process.env` fits. */
+export type Environment = Record<string, string | undefined>
+
+/** The environment a source's command starts with, or the class of reason it cannot start: never a value. */
+export type SourceEnvironment = { ok: true; environment: Environment } | { ok: false; reason: string }
+
+/** Why a source's secrets could not be resolved; `secret missing: <NAME>` comes from `secretMissing`. */
+export const SECRET_FAILURE = { unavailable: 'secret store unavailable' } as const
+
+export const secretMissing = (name: string): string => `secret missing: ${name}`
+
+type Resolved = { value: string } | { reason: string }
+
+/** Keychain first, then the environment; without either the reason names the keychain when it gave no answer. */
+const resolved = (name: string, lookup: SecretLookup, environment: Environment): Resolved => {
+  if (lookup.kind === SECRET_LOOKUP.found) return { value: lookup.value }
+  const fromEnvironment = environment[name]
+  if (fromEnvironment) return { value: fromEnvironment }
+  return { reason: lookup.kind === SECRET_LOOKUP.unavailable ? SECRET_FAILURE.unavailable : secretMissing(name) }
+}
+
+/**
+ * The environment of a source's command: `environment` with each of `names` set, looked up in the keychain first,
+ * then taken from `environment` itself. A name in neither fails the run with `secret missing: <NAME>`, or with
+ * `secret store unavailable` when the keychain gave no answer; the first such name in `names` decides. The lookups
+ * run side by side, so a keychain that hangs costs one lookup's time limit, not one per name. `environment` is not
+ * changed, and the answer is kept by no one: the caller hands it to the command and drops it.
+ */
+export const sourceEnvironment = async (
+  names: readonly string[],
+  lookup: SecretLookupFn,
+  environment: Environment,
+): Promise<SourceEnvironment> => {
+  if (names.length === 0) return { ok: true, environment: { ...environment } }
+  const lookups = await Promise.all(names.map((name) => lookup(name)))
+  const values: Record<string, string> = {}
+  for (const [index, name] of names.entries()) {
+    const entry = resolved(name, lookups[index] ?? { kind: SECRET_LOOKUP.absent }, environment)
+    if ('reason' in entry) return { ok: false, reason: entry.reason }
+    values[name] = entry.value
+  }
+  return { ok: true, environment: { ...environment, ...values } }
+}

package/src/secrets/hidden-input.ts

@@ -0,0 +1,51 @@
+/** Where typing a hidden value stands: still typing, ended with Enter, or cancelled (nothing is written then). */
+export type HiddenInput = { kind: 'typing'; value: string } | { kind: 'done'; value: string } | { kind: 'cancelled' }
+
+const ENTER = new Set(['\r', '\n'])
+const CANCEL = new Set(['\x03', '\x04'])
+const BACKSPACE = new Set(['\x7f', '\b'])
+const CLEAR_LINE = '\x15'
+const ESCAPE = '\x1b'
+const CSI_START = '['
+const SS3_START = 'O'
+
+const isControl = (character: string): boolean => (character.codePointAt(0) ?? 0) < 0x20
+
+/** The index after an escape sequence starting at `start` (the escape character): a CSI up to its final byte, SS3 and others one character. */
+const afterEscape = (characters: readonly string[], start: number): number => {
+  const introducer = characters[start + 1]
+  if (introducer === SS3_START) return start + 3
+  if (introducer !== CSI_START) return start + 2
+  let index = start + 2
+  while (index < characters.length) {
+    const code = characters[index]?.codePointAt(0) ?? 0
+    index += 1
+    if (code >= 0x40 && code <= 0x7e) return index
+  }
+  return index
+}
+
+/**
+ * One chunk of raw terminal input applied to the hidden value typed so far. Enter ends it, Ctrl-C or Ctrl-D cancel
+ * it, Backspace removes the last character and Ctrl-U the whole line; arrow keys and other escape sequences and
+ * further control characters are dropped. Whatever follows Enter in the same chunk is ignored.
+ */
+export const hiddenInputStep = (typed: string, chunk: string): HiddenInput => {
+  const characters = Array.from(chunk)
+  let value = Array.from(typed)
+  let index = 0
+  while (index < characters.length) {
+    const character = characters[index] ?? ''
+    if (ENTER.has(character)) return { kind: 'done', value: value.join('') }
+    if (CANCEL.has(character)) return { kind: 'cancelled' }
+    if (character === ESCAPE) {
+      index = afterEscape(characters, index)
+      continue
+    }
+    if (BACKSPACE.has(character)) value = value.slice(0, -1)
+    else if (character === CLEAR_LINE) value = []
+    else if (!isControl(character)) value.push(character)
+    index += 1
+  }
+  return { kind: 'typing', value: value.join('') }
+}