jackherd 0.0.1 → 1.0.1

package/src/sync/render.ts

@@ -0,0 +1,60 @@
+import type { JackherdConfig } from '../config'
+import { LANGUAGE_NAME, PLAN_VOCABULARY } from '../vocabulary'
+
+const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
+
+const WORKTREE_INCLUDE_COPY =
+  'cd <main-checkout> && git ls-files -z --others --ignored --exclude-from=.worktreeinclude | grep -zv node_modules | xargs -0 -I{} cp -p --parents {} <worktree>/'
+
+/** The command that copies a lane's untracked files; the schema keeps quotes out of every path. */
+const laneCopyCommand = (copy: readonly string[]): string =>
+  copy.length === 0
+    ? WORKTREE_INCLUDE_COPY
+    : `cd <main-checkout> && cp -p --parents -- ${copy.map((path) => `'${path}'`).join(' ')} <worktree>/`
+
+const prefixed = (prefix: string, values: Record<string, string>): [string, string][] =>
+  Object.entries(values).map(([key, value]) => [`kit.${prefix}.${key}`, value])
+
+/** Every placeholder a kit file may use, with its value for this project. */
+const placeholderValues = (config: JackherdConfig): Map<string, string> => {
+  const { header, sections, columns, phase } = PLAN_VOCABULARY[config.planLanguage]
+  return new Map([
+    ['kit.responseLanguage', LANGUAGE_NAME[config.responseLanguage]],
+    ['kit.planLanguage', LANGUAGE_NAME[config.planLanguage]],
+    ['kit.planDirectory', config.planDirectory],
+    ['kit.baseBranch', config.baseBranch],
+    ['kit.worktreeDirectory', config.worktreeDirectory],
+    ...prefixed('model', config.models),
+    ...prefixed('command', config.commands),
+    ['kit.lanes.copyCommand', laneCopyCommand(config.lanes.copy)],
+    ['kit.lanes.lockFile', config.lanes.lockFile],
+    ...prefixed('board', config.board),
+    ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
+  ])
+}
+
+/** The `kit.` placeholder names a template uses, in order of appearance. */
+export const listPlaceholders = (template: string): string[] =>
+  [...template.matchAll(PLACEHOLDER)].map(([, name]) => name)
+
+/**
+ * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
+ * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile>}}`,
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.heading.<key>}}` from the plan
+ * vocabulary, the two languages, the plan and worktree directory and the base branch. Other
+ * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project
+ * file unrendered. `overrides` win over the config: a global kit renders what each repository decides as
+ * `<name>` (`REPOSITORY_TOKENS`).
+ */
+export const renderTemplate = (
+  template: string,
+  config: JackherdConfig,
+  overrides: ReadonlyMap<string, string> = new Map(),
+): string => {
+  const values = placeholderValues(config)
+  return template.replace(PLACEHOLDER, (_match, name: string) => {
+    const value = overrides.get(name) ?? values.get(name)
+    if (value === undefined) throw new Error(`Unknown kit placeholder {{${name}}}`)
+    return value
+  })
+}

package/src/sync/report.ts

@@ -0,0 +1,96 @@
+import { CLI_NAME } from '../version/release'
+import { shownPath } from './kit-path'
+import { FILE_OUTCOME, type FileOutcome } from './plan-file'
+import { HOOK_OUTCOME, type HookOutcome } from './plan-hooks'
+import type { SyncResult } from './sync-result'
+
+export const SYNC_EXIT = { clean: 0, conflicts: 1, error: 2 } as const
+
+type Outcome = FileOutcome | HookOutcome
+
+const NEEDS_ATTENTION: readonly Outcome[] = [
+  FILE_OUTCOME.conflict,
+  FILE_OUTCOME.blocked,
+  HOOK_OUTCOME.conflict,
+  HOOK_OUTCOME.blocked,
+]
+
+const COUNTED: readonly Outcome[] = [
+  FILE_OUTCOME.created,
+  FILE_OUTCOME.updated,
+  FILE_OUTCOME.accepted,
+  FILE_OUTCOME.removed,
+  FILE_OUTCOME.unchanged,
+]
+
+const FILE_SECTIONS: { outcome: FileOutcome; heading: string; line: (path: string) => string }[] = [
+  {
+    outcome: FILE_OUTCOME.conflict,
+    heading: 'Conflicts: your file was kept, the kit version is next to it',
+    line: (path) => `  ${shownPath(path)} → ${shownPath(path)}.kit-new`,
+  },
+  {
+    outcome: FILE_OUTCOME.blocked,
+    heading: 'Blocked, nothing written: not a regular file, behind a symlink, or its .kit-new was edited',
+    line: (path) => `  ${shownPath(path)}`,
+  },
+  {
+    outcome: FILE_OUTCOME.kept,
+    heading: 'Kept with your changes (the kit has nothing new for them)',
+    line: (path) => `  ${shownPath(path)}`,
+  },
+  {
+    outcome: FILE_OUTCOME.deselected,
+    heading: 'Deleted by you, not recreated (`--accept <path>` brings one back)',
+    line: (path) => `  ${shownPath(path)}`,
+  },
+  {
+    outcome: FILE_OUTCOME.untracked,
+    heading: 'No longer in the kit, kept with your changes and no longer tracked',
+    line: (path) => `  ${shownPath(path)}`,
+  },
+  { outcome: FILE_OUTCOME.resolved, heading: 'Conflicts resolved', line: (path) => `  ${shownPath(path)}` },
+]
+
+const HOOK_SECTIONS: { outcome: HookOutcome; heading: string }[] = [
+  { outcome: HOOK_OUTCOME.conflict, heading: 'Hook conflicts: the kit version is in .claude/settings.json.kit-new' },
+  {
+    outcome: HOOK_OUTCOME.blocked,
+    heading: 'Hooks blocked: .claude/settings.json.kit-new was edited, not overwritten',
+  },
+  { outcome: HOOK_OUTCOME.deselected, heading: 'Kit hooks you removed or edited, left as they are' },
+]
+
+const RESOLVE_HINT = `Resolve a conflict: merge the .kit-new into your file and delete it, or run \`${CLI_NAME} sync --accept <path>\` to take the kit version.`
+
+export const exitCodeOf = (result: SyncResult): number => {
+  const outcomes = [...result.files, ...result.hooks].map(({ outcome }) => outcome)
+  return outcomes.some((outcome) => NEEDS_ATTENTION.includes(outcome)) ? SYNC_EXIT.conflicts : SYNC_EXIT.clean
+}
+
+const summaryLine = (outcomes: Outcome[]): string => {
+  const counts = COUNTED.map((outcome) => ({ outcome, count: outcomes.filter((each) => each === outcome).length }))
+  const nonZero = counts.filter(({ count }) => count > 0)
+  if (nonZero.length === 0) return `${CLI_NAME} sync: nothing to do`
+  return `${CLI_NAME} sync: ${nonZero.map(({ outcome, count }) => `${count} ${outcome}`).join(', ')}`
+}
+
+const section = (heading: string, lines: string[]): string[] => (lines.length > 0 ? ['', `${heading}:`, ...lines] : [])
+
+export const formatReport = (result: SyncResult): string => {
+  const fileLines = FILE_SECTIONS.flatMap(({ outcome, heading, line }) =>
+    section(
+      heading,
+      result.files.filter((file) => file.outcome === outcome).map(({ path }) => line(path)),
+    ),
+  )
+  const hookLines = HOOK_SECTIONS.flatMap(({ outcome, heading }) =>
+    section(
+      heading,
+      result.hooks.filter((hook) => hook.outcome === outcome).map(({ name }) => `  ${name}`),
+    ),
+  )
+  const hint = exitCodeOf(result) === SYNC_EXIT.conflicts ? ['', RESOLVE_HINT] : []
+  const summary = summaryLine([...result.files, ...result.hooks].map(({ outcome }) => outcome))
+  return [...(result.notes ?? []), summary, ...fileLines, ...hookLines, ...hint].join('\n')
+}

package/src/sync/settings-hooks.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod'
+import { canonicalJson, checksum } from './checksum'
+
+export type HookHandler = Record<string, unknown>
+
+export type HookGroup = { matcher?: string; hooks: HookHandler[]; [key: string]: unknown }
+
+export type Settings = { hooks?: Record<string, HookGroup[]>; [key: string]: unknown }
+
+export type SettingsResult = { ok: true; settings: Settings } | { ok: false; reason: string }
+
+export const HOOK_NAME = /^[a-z0-9][a-z0-9-]*$/
+
+/** One handler in `.claude/settings.json`, addressed by the event and matcher of its group. */
+export const hookDefinitionSchema = z.strictObject({
+  event: z.string().min(1),
+  matcher: z.string().optional(),
+  handler: z.record(z.string(), z.unknown()),
+})
+
+export type HookDefinition = z.infer<typeof hookDefinitionSchema>
+
+const hookGroupSchema = z.looseObject({
+  matcher: z.string().optional(),
+  hooks: z.array(z.record(z.string(), z.unknown())),
+})
+
+const settingsSchema = z.looseObject({ hooks: z.record(z.string(), z.array(hookGroupSchema)).optional() })
+
+export const parseSettings = (raw: unknown): SettingsResult => {
+  const parsed = settingsSchema.safeParse(raw)
+  if (!parsed.success) return { ok: false, reason: z.prettifyError(parsed.error) }
+  // The raw object, not `parsed.data`: Zod moves known keys first, which would reorder the file.
+  return { ok: true, settings: raw as Settings }
+}
+
+const sameMatcher = (left: string | undefined, right: string | undefined): boolean => (left ?? '') === (right ?? '')
+
+/**
+ * The identity of a kit hook: a checksum over event, matcher and the whole handler. A handler
+ * edited by hand gets a different key, so sync no longer recognises it as its own and leaves it.
+ */
+export const hookKey = (hook: HookDefinition): string =>
+  checksum(canonicalJson({ event: hook.event, matcher: hook.matcher ?? '', handler: hook.handler }))
+
+const isHandler = (hook: HookDefinition) => {
+  const wanted = canonicalJson(hook.handler)
+  return (handler: HookHandler): boolean => canonicalJson(handler) === wanted
+}
+
+/** Own keys only, so an event named `__proto__` or `constructor` reads as absent. */
+const groupsOf = (settings: Settings, event: string): HookGroup[] =>
+  settings.hooks && Object.hasOwn(settings.hooks, event) ? settings.hooks[event] : []
+
+export const containsHook = (settings: Settings, hook: HookDefinition): boolean =>
+  groupsOf(settings, hook.event).some(
+    (group) => sameMatcher(group.matcher, hook.matcher) && group.hooks.some(isHandler(hook)),
+  )
+
+/** Appends the hook in a group of its own, so no project group is rewritten. Returns a copy. */
+export const addHook = (settings: Settings, hook: HookDefinition): Settings => {
+  const group: HookGroup =
+    hook.matcher === undefined ? { hooks: [hook.handler] } : { matcher: hook.matcher, hooks: [hook.handler] }
+  const hooks = settings.hooks ?? {}
+  return { ...settings, hooks: { ...hooks, [hook.event]: [...groupsOf(settings, hook.event), group] } }
+}
+
+const withoutFirstMatch = (groups: HookGroup[], hook: HookDefinition): HookGroup[] => {
+  const matches = isHandler(hook)
+  const groupIndex = groups.findIndex((group) => sameMatcher(group.matcher, hook.matcher) && group.hooks.some(matches))
+  if (groupIndex === -1) return groups
+  const group = groups[groupIndex]
+  const handlerIndex = group.hooks.findIndex(matches)
+  const remaining = group.hooks.filter((_handler, index) => index !== handlerIndex)
+  const replacement = remaining.length > 0 ? [{ ...group, hooks: remaining }] : []
+  return [...groups.slice(0, groupIndex), ...replacement, ...groups.slice(groupIndex + 1)]
+}
+
+/**
+ * Removes one copy of the hook's handler. Only a group the removal empties disappears, and with it
+ * an emptied event and an emptied `hooks` object. Returns a copy.
+ */
+export const removeHook = (settings: Settings, hook: HookDefinition): Settings => {
+  if (!containsHook(settings, hook)) return settings
+  const remaining = withoutFirstMatch(groupsOf(settings, hook.event), hook)
+  const { [hook.event]: _removed, ...otherEvents } = settings.hooks ?? {}
+  const hooks = remaining.length > 0 ? { ...settings.hooks, [hook.event]: remaining } : otherEvents
+  const { hooks: _previous, ...rest } = settings
+  return Object.keys(hooks).length > 0 ? { ...rest, hooks } : rest
+}

package/src/sync/settings-migration.ts

@@ -0,0 +1,94 @@
+import { join } from 'node:path'
+import { CLAUDE_DIRECTORY, SETTINGS_FILE } from '../claude/paths'
+import { TOOL_DIRECTORY } from '../config/location'
+import {
+  applySettingsOffer,
+  isLegacyHookCommand,
+  isObject,
+  readSettingsOffer,
+  SESSION_HOOK_COMMAND,
+  type SettingsObject,
+  type SettingsOffer,
+} from './settings-offer'
+
+/** Where the global install's status line runs from, as `~/.claude/settings.json` names it. */
+export const GLOBAL_STATUS_LINE_COMMAND = `~/${TOOL_DIRECTORY}/statusline.sh`
+
+/** The status line commands earlier global installs wrote: before the rename, and the interim of 0.28 on main. */
+const LEGACY_STATUS_LINE_COMMANDS: readonly string[] = [
+  `~/${CLAUDE_DIRECTORY}/agent-kit/statusline.sh`,
+  `~/${CLAUDE_DIRECTORY}/jackherd/statusline.sh`,
+]
+
+const SHOWN_SETTINGS = `~/${CLAUDE_DIRECTORY}/${SETTINGS_FILE}`
+
+/** A status line on an old kit path points at the new one; any other key of it stays. */
+export const LEGACY_STATUS_LINE_MIGRATION: SettingsOffer = {
+  find: (settings) => {
+    const current = settings.statusLine
+    if (!isObject(current) || !LEGACY_STATUS_LINE_COMMANDS.includes(String(current.command))) return { kind: 'present' }
+    return { kind: 'add', next: { ...settings, statusLine: { ...current, command: GLOBAL_STATUS_LINE_COMMAND } } }
+  },
+}
+
+const migrateHandler = (handler: unknown): unknown =>
+  isObject(handler) && typeof handler.command === 'string' && isLegacyHookCommand(handler.command)
+    ? { ...handler, command: SESSION_HOOK_COMMAND }
+    : handler
+
+const migrateGroup = (group: unknown): unknown =>
+  isObject(group) && Array.isArray(group.hooks) ? { ...group, hooks: group.hooks.map(migrateHandler) } : group
+
+const sessionStartOf = (settings: SettingsObject): unknown[] | null => {
+  const hooks = settings.hooks
+  return isObject(hooks) && Array.isArray(hooks.SessionStart) ? hooks.SessionStart : null
+}
+
+/** Our `SessionStart` hook as the old CLI ran it becomes the `jh` command; every other event, group and handler stays. */
+export const LEGACY_HOOK_MIGRATION: SettingsOffer = {
+  find: (settings) => {
+    const groups = sessionStartOf(settings)
+    if (!groups) return { kind: 'present' }
+    const migrated = groups.map(migrateGroup)
+    if (JSON.stringify(migrated) === JSON.stringify(groups)) return { kind: 'present' }
+    return {
+      kind: 'add',
+      next: { ...settings, hooks: { ...(settings.hooks as SettingsObject), SessionStart: migrated } },
+    }
+  },
+}
+
+const HOOK_WAITS = `The SessionStart hook in ${SHOWN_SETTINGS} still runs agent-kit; once jh is on the PATH, change it to \`${SESSION_HOOK_COMMAND}\`.`
+
+/** Applies one migration; the line to print, or null when there was nothing to change. */
+const migrate = async (path: string, offer: SettingsOffer, done: string): Promise<string | null> => {
+  const read = await readSettingsOffer(path, offer)
+  if (read.plan.kind !== 'add') return null
+  const written = await applySettingsOffer(path, read)
+  return written.kind === 'written' ? done : `${SHOWN_SETTINGS} not changed: ${written.reason}`
+}
+
+/**
+ * Brings `~/.claude/settings.json` from an install before the rename to the new one: the status line moves with
+ * the script, the hook only when `jh` is on the PATH, since a hook naming a missing command fails every session.
+ * Writes nothing else and never throws; the lines say what changed or what is left.
+ */
+export const migrateGlobalSettings = async (home: string, cliOnPath: boolean): Promise<string[]> => {
+  const path = join(home, CLAUDE_DIRECTORY, SETTINGS_FILE)
+  const statusLine = await migrate(
+    path,
+    LEGACY_STATUS_LINE_MIGRATION,
+    `Pointed the status line in ${SHOWN_SETTINGS} at ${GLOBAL_STATUS_LINE_COMMAND}.`,
+  )
+  const hookPending = (await readSettingsOffer(path, LEGACY_HOOK_MIGRATION)).plan.kind === 'add'
+  const hook = !hookPending
+    ? null
+    : cliOnPath
+      ? await migrate(
+          path,
+          LEGACY_HOOK_MIGRATION,
+          `Changed the SessionStart hook in ${SHOWN_SETTINGS} to \`${SESSION_HOOK_COMMAND}\`.`,
+        )
+      : HOOK_WAITS
+  return [statusLine, hook].filter((line): line is string => line !== null)
+}

package/src/sync/settings-offer.ts

@@ -0,0 +1,168 @@
+import { randomBytes } from 'node:crypto'
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { CLI_NAME } from '../version/release'
+import { errorMessage } from './error-message'
+
+export type SettingsObject = Record<string, unknown>
+
+/** What one offer finds in parsed settings: done already, a change to make, or a foreign value in the way. */
+type OfferFinding =
+  | { kind: 'present' }
+  | { kind: 'add'; next: SettingsObject }
+  | { kind: 'foreign'; current: string; next: SettingsObject }
+  | { kind: 'unreadable'; reason: string }
+
+/** A setting `init` offers to write into a `settings.json`: the SessionStart hook or the status line. */
+export type SettingsOffer = { find: (settings: SettingsObject) => OfferFinding }
+
+export type SettingsPlan =
+  | { kind: 'present' }
+  | { kind: 'add'; content: string }
+  | { kind: 'foreign'; current: string; content: string }
+  | { kind: 'unreadable'; reason: string }
+
+/** The plan and the file it was made from, so applying it can tell whether the file changed meanwhile. */
+export type SettingsRead = { plan: SettingsPlan; text: string | undefined; mode: number }
+
+export type SettingsWrite = { kind: 'written' } | { kind: 'notWritten'; reason: string }
+
+/** What the `SessionStart` hook runs: a global sync only when the installed kit changed. */
+export const SESSION_HOOK_COMMAND = `${CLI_NAME} sync --global --if-changed`
+
+const SESSION_START = 'SessionStart'
+
+const SESSION_HOOK_GROUP = { matcher: 'startup', hooks: [{ type: 'command', command: SESSION_HOOK_COMMAND }] }
+
+/** Claude Code creates `settings.json` world-readable; an existing file keeps its own mode. */
+const NEW_FILE_MODE = 0o644
+
+export const isObject = (value: unknown): value is SettingsObject =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/** A foreign command is shown in a question; an escape sequence in it must not redraw the terminal. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the class exists to replace control characters
+const withoutControlCharacters = (text: string): string => text.replace(/[\x00-\x1f\x7f]/g, '?')
+
+/** Our hook in any start form (`jh …`, `bunx jackherd …`, and the old `agent-kit …`) and any flag order. */
+const isHookOf = (command: string, cli: RegExp): boolean => {
+  const words = command.trim().split(/\s+/)
+  const kit = words.findIndex((word) => cli.test(word))
+  return kit !== -1 && words[kit + 1] === 'sync' && words.includes('--global') && words.includes('--if-changed')
+}
+
+const isOurHookCommand = (command: string): boolean => isHookOf(command, /(^|\/)(jh|jackherd|agent-kit)$/)
+
+/** The exact forms the CLI wrote before the rename; anything composed around them is the user's and stays. */
+const LEGACY_HOOK = /^(bunx (@crossdelta\/)?)?agent-kit sync (--global --if-changed|--if-changed --global)$/
+
+/** Our hook as the CLI started before the rename (`agent-kit …`, `bunx @crossdelta/agent-kit …`), nothing around it. */
+export const isLegacyHookCommand = (command: string): boolean => LEGACY_HOOK.test(command.trim())
+
+/** Reads only what it recognises; a group or handler of any other shape is someone else's and is skipped. */
+const holdsOurHook = (groups: unknown[]): boolean =>
+  groups.some(
+    (group) =>
+      isObject(group) &&
+      Array.isArray(group.hooks) &&
+      group.hooks.some(
+        (handler) => isObject(handler) && typeof handler.command === 'string' && isOurHookCommand(handler.command),
+      ),
+  )
+
+/** The hook as a group of its own appended to `SessionStart`; every other event, group and handler is copied. */
+export const SESSION_HOOK_OFFER: SettingsOffer = {
+  find: (settings) => {
+    const hooks = settings.hooks ?? {}
+    if (!isObject(hooks)) return { kind: 'unreadable', reason: '`hooks` is not an object' }
+    const groups = Object.hasOwn(hooks, SESSION_START) ? hooks[SESSION_START] : []
+    if (!Array.isArray(groups)) return { kind: 'unreadable', reason: `\`hooks.${SESSION_START}\` is not a list` }
+    if (holdsOurHook(groups)) return { kind: 'present' }
+    return { kind: 'add', next: { ...settings, hooks: { ...hooks, [SESSION_START]: [...groups, SESSION_HOOK_GROUP] } } }
+  },
+}
+
+/** `command` as the status line; one of any other shape or command is the user's and is named, never dropped silently. */
+export const statusLineOffer = (command: string): SettingsOffer => ({
+  find: (settings) => {
+    const next = { ...settings, statusLine: { type: 'command', command } }
+    if (!Object.hasOwn(settings, 'statusLine')) return { kind: 'add', next }
+    const current = settings.statusLine
+    if (isObject(current) && current.command === command) return { kind: 'present' }
+    const shown = isObject(current) && typeof current.command === 'string' ? current.command : JSON.stringify(current)
+    return { kind: 'foreign', current: withoutControlCharacters(shown), next }
+  },
+})
+
+const serialize = (settings: SettingsObject): string => `${JSON.stringify(settings, null, 2)}\n`
+
+const parseSettings = (text: string): SettingsObject | string => {
+  try {
+    const value: unknown = JSON.parse(text)
+    return isObject(value) ? value : 'not a JSON object'
+  } catch (err) {
+    return `not valid JSON (${errorMessage(err)})`
+  }
+}
+
+/**
+ * What the offer takes in a `settings.json` holding `text` (undefined when there is none). Settings the offer
+ * cannot merge into without touching what is there are `unreadable`, never an error.
+ */
+export const planSettingsOffer = (text: string | undefined, offer: SettingsOffer): SettingsPlan => {
+  const settings = text === undefined ? {} : parseSettings(text)
+  if (typeof settings === 'string') return { kind: 'unreadable', reason: settings }
+  const finding = offer.find(settings)
+  if (finding.kind === 'add') return { kind: 'add', content: serialize(finding.next) }
+  if (finding.kind === 'foreign') return { kind: 'foreign', current: finding.current, content: serialize(finding.next) }
+  return finding
+}
+
+const isMissing = (err: unknown): boolean => isObject(err) && err.code === 'ENOENT'
+
+/** The file's text and mode; undefined text when there is none. Anything but a regular file is refused. */
+const readSettingsFile = async (path: string): Promise<{ text: string | undefined; mode: number } | string> => {
+  try {
+    const entry = await lstat(path)
+    if (!entry.isFile()) return 'not a regular file (a symlink is never written through)'
+    return { text: await readFile(path, 'utf8'), mode: entry.mode & 0o777 }
+  } catch (err) {
+    return isMissing(err) ? { text: undefined, mode: NEW_FILE_MODE } : errorMessage(err)
+  }
+}
+
+/** Reads `path` and plans the offer against it; never throws. */
+export const readSettingsOffer = async (path: string, offer: SettingsOffer): Promise<SettingsRead> => {
+  const file = await readSettingsFile(path)
+  if (typeof file === 'string')
+    return { plan: { kind: 'unreadable', reason: file }, text: undefined, mode: NEW_FILE_MODE }
+  return { plan: planSettingsOffer(file.text, offer), text: file.text, mode: file.mode }
+}
+
+/** Through a temporary file and a rename, so the settings are never half written. */
+const replaceFile = async (path: string, content: string, mode: number): Promise<void> => {
+  const temporary = `${path}.jackherd-${randomBytes(6).toString('hex')}.tmp`
+  try {
+    await writeFile(temporary, content, { flag: 'wx', mode })
+    await rename(temporary, path)
+  } finally {
+    await rm(temporary, { force: true })
+  }
+}
+
+/**
+ * Writes the planned change, unless the file changed since it was read (the user may have taken a while to
+ * answer): then nothing is written and the result says why. Never throws.
+ */
+export const applySettingsOffer = async (path: string, read: SettingsRead): Promise<SettingsWrite> => {
+  if (read.plan.kind !== 'add' && read.plan.kind !== 'foreign')
+    return { kind: 'notWritten', reason: 'nothing to write' }
+  const now = await readSettingsFile(path)
+  if (typeof now === 'string') return { kind: 'notWritten', reason: now }
+  if (now.text !== read.text) return { kind: 'notWritten', reason: 'it changed while the question was open' }
+  try {
+    await replaceFile(path, read.plan.content, now.mode)
+    return { kind: 'written' }
+  } catch (err) {
+    return { kind: 'notWritten', reason: errorMessage(err) }
+  }
+}

package/src/sync/setup-questions.ts

@@ -0,0 +1,70 @@
+import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
+import { LANGUAGE_NAME, PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import type { Choice } from './choice'
+import type { CommandContext } from './command-context'
+import { type SetupAnswers, type SetupOutcome, setupValues } from './setup'
+import { INSTALLERS, type ToolPresence } from './tools'
+
+const LANGUAGE_CHOICES: readonly Choice<PlanLanguage>[] = [PLAN_LANGUAGE.en, PLAN_LANGUAGE.de].map((value) => ({
+  value,
+  label: LANGUAGE_NAME[value],
+}))
+
+const ADAPTER_CHOICES: readonly Choice<TerminalAdapter>[] = [
+  { value: TERMINAL_ADAPTER.herdr, label: 'Yes, use herdr (agent states and context fill in the plans view)' },
+  { value: TERMINAL_ADAPTER.none, label: 'No, not now' },
+]
+
+const RESPONSE_QUESTION = 'Which language should the skills answer you in?'
+
+const PLAN_QUESTION = 'Which language should plans and boards be written in? It sets their headings.'
+
+const ADAPTER_QUESTION =
+  'Use herdr? It runs parallel lanes for /orchestrate and shows each agent in the plans view; /plan and /implement work without it.'
+
+const INSTALL_QUESTION = `herdr is not installed. It is only needed for parallel lanes. Install it now with its official installer, \`${INSTALLERS.herdr}\`?`
+
+/**
+ * The line after an install that left no herdr to run: a failed download or script ends with its exit code, and an
+ * installer that ends with 0 may still put herdr into a directory this process's PATH does not hold yet.
+ */
+const installOutcome = (exitCode: number): string =>
+  exitCode === 0
+    ? `The herdr installer finished, but herdr is not on the PATH of this shell. Open a new shell and run \`herdr --version\`; if it is missing there too, run the installer yourself: ${INSTALLERS.herdr}`
+    : `The herdr installer ended with exit code ${exitCode}. Run it yourself when you want herdr: ${INSTALLERS.herdr}`
+
+/**
+ * Offers the official herdr installer when herdr is missing and the platform has one; runs it only after a yes.
+ * Returns the tools as found afterwards. A failed install is a line, never a failed `init`.
+ */
+const offerHerdrInstall = async (context: CommandContext, tools: ToolPresence): Promise<ToolPresence> => {
+  if (tools.herdr || !tools.herdrInstallable) return tools
+  if ((await context.ask(INSTALL_QUESTION)) !== true) return tools
+  context.log(`Running ${INSTALLERS.herdr}`)
+  const exitCode = context.runInstaller('herdr')
+  const found = context.detectTools()
+  if (!found.herdr) context.log(installOutcome(exitCode))
+  return found
+}
+
+/** The three answers, or null as soon as one cannot be asked (no terminal). */
+const askAnswers = async (context: CommandContext, tools: ToolPresence): Promise<SetupAnswers | null> => {
+  const responseLanguage = await context.choose(RESPONSE_QUESTION, LANGUAGE_CHOICES, PLAN_LANGUAGE.en)
+  if (responseLanguage === null) return null
+  const planLanguage = await context.choose(PLAN_QUESTION, LANGUAGE_CHOICES, responseLanguage)
+  if (planLanguage === null) return null
+  const found = await offerHerdrInstall(context, tools)
+  const fallback = found.herdr ? TERMINAL_ADAPTER.herdr : TERMINAL_ADAPTER.none
+  const adapter = await context.choose(ADAPTER_QUESTION, ADAPTER_CHOICES, fallback)
+  return adapter === null ? null : { responseLanguage, planLanguage, adapter }
+}
+
+/**
+ * The setup for a new config. `answer` is the command line's `--yes`/`--no`: with it nothing is asked and nothing
+ * is installed, and the defaults apply, as they do without a terminal.
+ */
+export const chooseSetup = async (context: CommandContext, answer: boolean | undefined): Promise<SetupOutcome> => {
+  const tools = context.detectTools()
+  const answers = answer === undefined ? await askAnswers(context, tools) : null
+  return setupValues(answers, tools)
+}

package/src/sync/setup.ts

@@ -0,0 +1,52 @@
+import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
+import { LANGUAGE_NAME, PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import type { ToolPresence } from './tools'
+
+/** What `init` asks before it writes a new config. */
+export type SetupAnswers = { responseLanguage: PlanLanguage; planLanguage: PlanLanguage; adapter: TerminalAdapter }
+
+/** The config values the setup decides, in the shape of the config. */
+export type SetupConfig = {
+  responseLanguage: PlanLanguage
+  planLanguage: PlanLanguage
+  terminal: { adapter: TerminalAdapter }
+}
+
+/** The values for a new config and, when nobody was asked, the line that says which defaults were taken. */
+export type SetupOutcome = { values: SetupConfig; note: string | null }
+
+/** What a run without questions takes: English for both, herdr as the adapter only where herdr is installed. */
+export const setupDefaults = (tools: ToolPresence): SetupAnswers => ({
+  responseLanguage: PLAN_LANGUAGE.en,
+  planLanguage: PLAN_LANGUAGE.en,
+  adapter: tools.herdr ? TERMINAL_ADAPTER.herdr : TERMINAL_ADAPTER.none,
+})
+
+const toConfig = ({ responseLanguage, planLanguage, adapter }: SetupAnswers): SetupConfig => ({
+  responseLanguage,
+  planLanguage,
+  terminal: { adapter },
+})
+
+const languagesText = ({ responseLanguage, planLanguage }: SetupAnswers): string =>
+  responseLanguage === planLanguage
+    ? `replies and plans in ${LANGUAGE_NAME[responseLanguage]}`
+    : `replies in ${LANGUAGE_NAME[responseLanguage]}, plans in ${LANGUAGE_NAME[planLanguage]}`
+
+const herdrFoundText = (tools: ToolPresence): string => (tools.herdr ? 'found herdr' : 'herdr not found')
+
+const adapterText = (adapter: TerminalAdapter, tools: ToolPresence): string =>
+  `${adapter === TERMINAL_ADAPTER.herdr ? 'herdr as the terminal adapter' : 'no terminal adapter'} (${herdrFoundText(tools)})`
+
+/**
+ * The setup for a new config. `answers` is null when nobody could be asked (`--yes`, `--no`, no terminal); the
+ * defaults of `setupDefaults` apply then, and the note names them.
+ */
+export const setupValues = (answers: SetupAnswers | null, tools: ToolPresence): SetupOutcome => {
+  if (answers !== null) return { values: toConfig(answers), note: null }
+  const defaults = setupDefaults(tools)
+  return {
+    values: toConfig(defaults),
+    note: `Not asked about the setup: ${languagesText(defaults)}, ${adapterText(defaults.adapter, tools)}. Change them in the config.`,
+  }
+}