jackherd 0.0.1 → 1.0.0

package/src/sync/command.ts

@@ -0,0 +1,94 @@
+import { CLI_NAME } from '../version/release'
+import {
+  type CommandContext,
+  defaultContext,
+  GLOBAL_FLAG,
+  globalTargetNote,
+  runWithKit,
+  usageError,
+} from './command-context'
+import { errorMessage } from './error-message'
+import { dailyUpdateNotice, defaultUpdateCheck, lockedVersion, syncNeeded, type UpdateCheck } from './if-changed'
+import { SYNC_EXIT } from './report'
+import { migrateGlobalSettings } from './settings-migration'
+import { runGlobalSync, runSync } from './sync'
+
+export type SyncArgs =
+  | { ok: true; accept: string[]; global: boolean; ifChanged: boolean }
+  | { ok: false; message: string }
+
+const ACCEPT_FLAG = '--accept'
+const IF_CHANGED_FLAG = '--if-changed'
+
+const SYNC_USAGE = `Usage: ${CLI_NAME} sync [--global [${IF_CHANGED_FLAG}]] [--accept <path>]...`
+
+export const parseSyncArgs = (args: string[]): SyncArgs => {
+  const accept: string[] = []
+  let global = false
+  let ifChanged = false
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === GLOBAL_FLAG) {
+      global = true
+      continue
+    }
+    if (arg === IF_CHANGED_FLAG) {
+      ifChanged = true
+      continue
+    }
+    if (arg.startsWith(`${ACCEPT_FLAG}=`)) {
+      accept.push(arg.slice(ACCEPT_FLAG.length + 1))
+      continue
+    }
+    if (arg !== ACCEPT_FLAG) return { ok: false, message: `Unknown argument: ${arg}\n${SYNC_USAGE}` }
+    const path = args[++i]
+    if (path === undefined) return { ok: false, message: `${ACCEPT_FLAG} needs a path\n${SYNC_USAGE}` }
+    accept.push(path)
+  }
+  if (ifChanged && !global) return { ok: false, message: `${IF_CHANGED_FLAG} goes with ${GLOBAL_FLAG}\n${SYNC_USAGE}` }
+  return { ok: true, accept, global, ifChanged }
+}
+
+const syncGlobal = (context: CommandContext, accept: string[]): Promise<number> =>
+  runWithKit(context, 'sync', async (kit) => {
+    const result = await runGlobalSync({ home: context.home, kit, accept, configHome: context.configHome })
+    const settings = await migrateGlobalSettings(context.home, context.cliOnPath())
+    return { notes: [globalTargetNote(context.home), ...settings], result }
+  })
+
+/**
+ * `sync --global --if-changed`, meant for a `SessionStart` hook: syncs `~/.claude` only when the installed package
+ * is not the version the global lock was written by, and once a day names a newer release on npm in one line.
+ * Prints nothing when there is nothing to do, since a hook's output reaches the session. Installs nothing.
+ */
+const syncGlobalIfChanged = async (context: CommandContext, accept: string[], check: UpdateCheck): Promise<number> => {
+  let installed: string
+  try {
+    installed = (await context.locate()).version
+  } catch (err) {
+    context.log(`${CLI_NAME} sync failed: ${errorMessage(err)}`)
+    return SYNC_EXIT.error
+  }
+  const exitCode = syncNeeded(installed, await lockedVersion(context.home)) ? await syncGlobal(context, accept) : 0
+  const notice = await dailyUpdateNotice(context.home, installed, check)
+  if (notice) context.log(notice)
+  return exitCode
+}
+
+export const runSyncCommand = async (
+  args: string[],
+  context: CommandContext = defaultContext(),
+  check: UpdateCheck = defaultUpdateCheck(),
+): Promise<number> => {
+  const parsed = parseSyncArgs(args)
+  if (!parsed.ok) return usageError(context, parsed.message)
+  const { accept, global, ifChanged } = parsed
+  if (ifChanged) return syncGlobalIfChanged(context, accept, check)
+  if (global) return syncGlobal(context, accept)
+  return runWithKit(context, 'sync', async (kit) => ({
+    notes: [],
+    result: await runSync({ projectRoot: context.projectRoot, home: context.home, kit, accept }),
+  }))
+}
+
+export const run = (args: string[]): Promise<number> => runSyncCommand(args)

package/src/sync/error-message.ts

@@ -0,0 +1 @@
+export const errorMessage = (err: unknown): string => (err instanceof Error ? err.message : String(err))

package/src/sync/gitignore.ts

@@ -0,0 +1,45 @@
+import { lstat, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+
+/** What the kit's skills write per lane and nobody commits: the hand-over notes of a lane that changes chat. */
+export const KIT_IGNORED_PATHS: readonly string[] = [`${claudePath(HANDOVER_DIRECTORY)}/`]
+
+const GITIGNORE = '.gitignore'
+
+const isMissing = (err: unknown): boolean =>
+  typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT'
+
+const readExisting = async (path: string): Promise<string | undefined> => {
+  try {
+    const entry = await lstat(path)
+    if (!entry.isFile()) throw new Error(`${GITIGNORE} is not a regular file`)
+    return await readFile(path, 'utf8')
+  } catch (err) {
+    if (isMissing(err)) return undefined
+    throw err
+  }
+}
+
+const missingLines = (text: string, lines: readonly string[]): string[] => {
+  const present = new Set(text.split('\n').map((line) => line.trim()))
+  return lines.filter((line) => !present.has(line))
+}
+
+/**
+ * Adds the lines the project's `.gitignore` lacks, at its end; a file that does not exist is created. A line
+ * that is already there (whatever surrounds it) is left alone, so a second run changes nothing. Returns the
+ * lines it added. Throws when `.gitignore` is a symlink or a directory: nothing is written through it.
+ */
+export const ensureGitignoreLines = async (
+  projectRoot: string,
+  lines: readonly string[] = KIT_IGNORED_PATHS,
+): Promise<string[]> => {
+  const path = join(projectRoot, GITIGNORE)
+  const existing = await readExisting(path)
+  const missing = missingLines(existing ?? '', lines)
+  if (missing.length === 0) return []
+  const separator = existing === undefined || existing === '' || existing.endsWith('\n') ? '' : '\n'
+  await writeFile(path, `${existing ?? ''}${separator}${missing.join('\n')}\n`)
+  return missing
+}

package/src/sync/global-kit.ts

@@ -0,0 +1,176 @@
+import { AGENTS_DIRECTORY, claudePath, RULES_DIRECTORY, SKILLS_DIRECTORY } from '../claude/paths'
+import { SKILL_PREFIX } from '../config'
+import { TOOL_DIRECTORY } from '../config/location'
+import { REPOSITORY_TOKENS } from '../config/repository-values'
+import { CLI_NAME, PACKAGE_NAME } from '../version/release'
+import type { KitFile, KitSource } from './kit'
+import { TOOL_ROOT } from './kit-path'
+import { listPlaceholders } from './render'
+
+export type EntryKind = 'skill' | 'agent'
+
+/** Where the kit's rules land: in `~/.jackherd/rules/`, outside `~/.claude/`, so Claude Code does not load them in every project. */
+const GLOBAL_RULES_DIRECTORY = `${TOOL_ROOT}/${RULES_DIRECTORY}`
+
+/** Put at the top of a global file that names values each repository decides; `sync --global` renders them as `<name>`. */
+export const REPOSITORY_VALUES_NOTE = `Values in angle brackets such as \`<test>\`, \`<install>\` or \`<baseBranch>\` are the current repository's own: run \`${CLI_NAME} config\` once in it to read them all, or \`${CLI_NAME} config <name>\` for one.`
+
+const SKILL_PATH = new RegExp(`^${SKILLS_DIRECTORY}/([^/]+)/(.+)$`)
+const AGENT_PATH = new RegExp(`^${AGENTS_DIRECTORY}/([^/]+)\\.md$`)
+const SKILL_ENTRY = new RegExp(`^${SKILLS_DIRECTORY}/[^/]+/SKILL\\.md$`)
+const RULE_PATH = new RegExp(`^${RULES_DIRECTORY}/kit/(.+)$`)
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/
+const NAME_LINE = /^name: (.+)$/m
+const DESCRIPTION_LINE = /^description: '(.*)'$/m
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+export const globalNote = (name: string, kind: EntryKind): string =>
+  `Global ${PACKAGE_NAME} copy. In a project that has its own ${name} ${kind}, use that one instead. `
+
+const assertUsablePrefix = (prefix: string): void => {
+  if (!SKILL_PREFIX.test(prefix)) {
+    throw new Error(`skillPrefix "${prefix}" is not usable: lower-case letters and digits ending in a dash, e.g. jh-`)
+  }
+}
+
+/** Where the status line lands: `~/.jackherd/statusline.sh`; `init --global` offers it from there. */
+const GLOBAL_STATUS_LINE_PATH = `${TOOL_ROOT}/statusline.sh`
+
+/** The path in a project's `.claude/`: skills and agents prefixed, everything else where the kit puts it. */
+const projectPath = (path: string, prefix: string): string => {
+  const skill = SKILL_PATH.exec(path)
+  if (skill) return `${SKILLS_DIRECTORY}/${prefix}${skill[1]}/${skill[2]}`
+  const agent = AGENT_PATH.exec(path)
+  return agent ? `${AGENTS_DIRECTORY}/${prefix}${agent[1]}.md` : path
+}
+
+/** The path in `~/.claude`, or null for what stays out of a global install (the hooks). */
+const globalPath = (path: string, prefix: string): string | null => {
+  if (path === 'statusline.sh') return GLOBAL_STATUS_LINE_PATH
+  const rule = RULE_PATH.exec(path)
+  if (rule) return `${GLOBAL_RULES_DIRECTORY}/${rule[1]}`
+  return SKILL_PATH.test(path) || AGENT_PATH.test(path) ? projectPath(path, prefix) : null
+}
+
+const entryKind = (path: string): EntryKind | null => {
+  if (SKILL_ENTRY.test(path)) return 'skill'
+  if (AGENT_PATH.test(path)) return 'agent'
+  return null
+}
+
+/** Skill and agent names the kit ships, longest first so `pre-commit` wins over a shorter name inside it. */
+const kitNames = (files: KitFile[]): string[] => {
+  const names = files.flatMap(({ path }) => {
+    const match = SKILL_PATH.exec(path) ?? AGENT_PATH.exec(path)
+    return match ? [match[1]] : []
+  })
+  return [...new Set(names)].sort((left, right) => right.length - left.length)
+}
+
+/** Names as a skill or agent calls another: slash commands, `subagent_type`, backticked names, relative links. */
+const rewriteNames = (text: string, alternation: string, prefix: string): string =>
+  text
+    .replace(
+      new RegExp(`\\.\\./${SKILLS_DIRECTORY}/(${alternation})(?![\\w-])`, 'g'),
+      `../${SKILLS_DIRECTORY}/${prefix}$1`,
+    )
+    .replace(new RegExp(`(?<![\\w.~/-])/(${alternation})(?![\\w/-])`, 'g'), `/${prefix}$1`)
+    .replace(new RegExp(`subagent_type: '(${alternation})'`, 'g'), `subagent_type: '${prefix}$1'`)
+    .replace(new RegExp(`\`(${alternation})\``, 'g'), `\`${prefix}$1\``)
+
+const PROJECT_SKILLS = claudePath(SKILLS_DIRECTORY)
+const GLOBAL_SKILLS = `~/${PROJECT_SKILLS}`
+
+/** `.claude/skills/<name>/` as the copy in `skillsDirectory` (`~/.claude/skills` or the project's own). */
+const rewriteSkillPaths = (text: string, alternation: string, prefix: string, skillsDirectory: string): string =>
+  text.replace(
+    new RegExp(`(?<![~\\w/])${escapeRegExp(PROJECT_SKILLS)}/(${alternation})/`, 'g'),
+    `${skillsDirectory}/${prefix}$1/`,
+  )
+
+const rewriteReferences = (text: string, names: string[], prefix: string): string => {
+  const alternation = names.map(escapeRegExp).join('|')
+  return rewriteNames(rewriteSkillPaths(text, alternation, prefix, GLOBAL_SKILLS), alternation, prefix).replace(
+    new RegExp(`(?<![~\\w/])${escapeRegExp(claudePath(RULES_DIRECTORY))}/kit/(?=[\\w-]+\\.md)`, 'g'),
+    `~/${TOOL_DIRECTORY}/${RULES_DIRECTORY}/`,
+  )
+}
+
+const rewriteFrontmatter = (file: KitFile, prefix: string, note: (name: string) => string): string => {
+  const block = FRONTMATTER.exec(file.template)
+  if (!block) throw new Error(`Kit file ${file.path} has no frontmatter`)
+  const name = NAME_LINE.exec(block[1])?.[1].trim()
+  if (!name || !DESCRIPTION_LINE.test(block[1])) {
+    throw new Error(`Kit file ${file.path} needs a name line and a single-quoted description line`)
+  }
+  const head = block[1]
+    .replace(NAME_LINE, `name: ${prefix}${name}`)
+    .replace(DESCRIPTION_LINE, (_line, text: string) => `description: '${note(name)}${text}'`)
+  return `---\n${head}\n---\n${file.template.slice(block[0].length)}`
+}
+
+const usesRepositoryValues = (template: string): boolean =>
+  listPlaceholders(template).some((name) => REPOSITORY_TOKENS.has(name))
+
+/** The note right after the frontmatter, or first when there is none. */
+const withRepositoryNote = (template: string): string => {
+  const block = FRONTMATTER.exec(template)
+  const head = block ? block[0] : ''
+  const rest = template.slice(head.length).replace(/^\n+/, '')
+  return `${head}${head ? '\n' : ''}${REPOSITORY_VALUES_NOTE}\n\n${rest}`
+}
+
+const toGlobalFile = (file: KitFile, path: string, names: string[], prefix: string): KitFile => {
+  if (!file.path.endsWith('.md')) return { ...file, path }
+  const kind = entryKind(file.path)
+  const noted =
+    kind === 'skill' || usesRepositoryValues(file.template) ? withRepositoryNote(file.template) : file.template
+  const body = rewriteReferences(noted, names, prefix)
+  const template = kind
+    ? rewriteFrontmatter({ ...file, template: body }, prefix, (name) => globalNote(name, kind))
+    : body
+  return { ...file, path, template }
+}
+
+/**
+ * The kit as `~/.claude` receives it: skills and agents renamed with the prefix, rules and the status line
+ * moved into `~/.jackherd/`, hooks left out. Inside Markdown files, every reference
+ * follows: slash commands, `subagent_type`, backticked names, skill and rule paths. A global copy
+ * needs the prefix because a personal skill shadows a project skill of the same name.
+ */
+export const toGlobalKit = (kit: KitSource, prefix: string): KitSource => {
+  assertUsablePrefix(prefix)
+  const names = kitNames(kit.files)
+  const files = kit.files.flatMap((file) => {
+    const path = globalPath(file.path, prefix)
+    return path ? [toGlobalFile(file, path, names, prefix)] : []
+  })
+  return { version: kit.version, files, hooksTemplate: undefined }
+}
+
+const toProjectFile = (file: KitFile, names: string[], prefix: string): KitFile => {
+  const path = projectPath(file.path, prefix)
+  if (!file.path.endsWith('.md') || file.path.startsWith('hooks/')) return { ...file, path }
+  const alternation = names.map(escapeRegExp).join('|')
+  const body = rewriteNames(rewriteSkillPaths(file.template, alternation, prefix, PROJECT_SKILLS), alternation, prefix)
+  const kind = entryKind(file.path)
+  return {
+    ...file,
+    path,
+    template: kind ? rewriteFrontmatter({ ...file, template: body }, prefix, () => '') : body,
+  }
+}
+
+/**
+ * The kit as a project with `skillPrefix` receives it: skills and agents renamed, every reference to them
+ * following (as in `toGlobalKit`), rules, hooks and the status line in place. A project skill of the same name
+ * then stays the project's, and the kit skills call each other, not it. Without a prefix the kit is returned as it is.
+ */
+export const toProjectKit = (kit: KitSource, prefix: string): KitSource => {
+  if (prefix === '') return kit
+  assertUsablePrefix(prefix)
+  const names = kitNames(kit.files)
+  return { ...kit, files: kit.files.map((file) => toProjectFile(file, names, prefix)) }
+}

package/src/sync/herdr-plugin.ts

@@ -0,0 +1,175 @@
+import { realpathSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isLinkedWorktree } from '../plans/git'
+import { herdrBinary, spawnTool, type ToolRun } from './tools'
+
+export const HERDR_PLUGIN_ID = 'crossdelta.jackherd'
+
+/** The plugin id before the rename; `sync` unlinks it once the current id is linked, so it is replaced, not doubled. */
+export const LEGACY_HERDR_PLUGIN_ID = 'crossdelta.agent-kit'
+
+/** The plugin's directory below the package root; `package.json` ships it through `files`. */
+export const HERDR_PLUGIN_DIRECTORY = 'herdr-plugin'
+
+/** Why the plugin is linked again: herdr does not list it, it points at another directory, or its manifest is unreadable. */
+export const RELINK_REASON = { missing: 'missing', elsewhere: 'elsewhere', manifest: 'manifest' } as const
+
+export type RelinkReason = (typeof RELINK_REASON)[keyof typeof RELINK_REASON]
+
+/**
+ * Where the running package lies: a checkout of the kit's source, a lane's worktree (whose path goes away with the
+ * lane), or an installed package (global, `bunx` cache, a project's dependency).
+ */
+export const PACKAGE_COPY = { checkout: 'checkout', laneWorktree: 'laneWorktree', installed: 'installed' } as const
+
+export type PackageCopy = (typeof PACKAGE_COPY)[keyof typeof PACKAGE_COPY]
+
+/** One herdr command; `missing` is true when there is no `herdr` to run at all. */
+export type HerdrRun = (args: string[]) => ToolRun
+
+export type LinkRequest = {
+  packageRoot: string
+  env: Record<string, string | undefined>
+  run: HerdrRun
+  /** What this copy may link: see `linkHerdrPlugin`. */
+  copy: PackageCopy
+  /** The id an install before the rename linked; `LEGACY_HERDR_PLUGIN_ID` unless a test names another. */
+  legacyPluginId?: string
+}
+
+/** The kit plugin as herdr has it linked. */
+export type LinkedPlugin = { root: string; warnings: string[] }
+
+type ListedPlugin = { plugin_id?: unknown; plugin_root?: unknown; warnings?: unknown }
+
+/** The kit plugin in a `herdr plugin list --json` answer, null when it is not there; throws on another shape. */
+export const linkedPluginOf = (json: string, id: string = HERDR_PLUGIN_ID): LinkedPlugin | null => {
+  const plugins = (JSON.parse(json) as { result?: { plugins?: unknown } }).result?.plugins
+  if (!Array.isArray(plugins)) throw new Error('herdr plugin list: unexpected answer')
+  const listed = (plugins as ListedPlugin[]).find((plugin) => plugin?.plugin_id === id)
+  if (!listed) return null
+  const warnings = Array.isArray(listed.warnings) ? listed.warnings.filter((each) => typeof each === 'string') : []
+  return { root: String(listed.plugin_root), warnings }
+}
+
+const manifestWarningOf = (linked: LinkedPlugin): string | undefined =>
+  linked.warnings.find((warning) => warning.startsWith('manifest'))
+
+/** Why the link has to be made again, null when it points at `expected` and herdr can read its manifest. */
+export const relinkReasonOf = (linked: LinkedPlugin | null, expected: string): RelinkReason | null => {
+  if (!linked) return RELINK_REASON.missing
+  if (manifestWarningOf(linked)) return RELINK_REASON.manifest
+  return resolve(linked.root) === resolve(expected) ? null : RELINK_REASON.elsewhere
+}
+
+/** The reason as the output line says it: herdr's own warning for the manifest, else what made the link wrong. */
+const reasonText = (reason: RelinkReason, linked: LinkedPlugin): string =>
+  reason === RELINK_REASON.manifest ? (manifestWarningOf(linked) ?? 'manifest') : 'it pointed at another package'
+
+/** A lane's worktree never links or unlinks: it names a broken link to this copy's directory, nothing else. */
+const laneNote = (linked: LinkedPlugin | null, packageRoot: string): string | null =>
+  relinkReasonOf(linked, join(packageRoot, HERDR_PLUGIN_DIRECTORY)) === null ? null : staleLinkNote(linked)
+
+/** What a lane's worktree says about the link: only a broken one is worth a line, since it never relinks from there. */
+const staleLinkNote = (linked: LinkedPlugin | null): string | null => {
+  const warning = linked && manifestWarningOf(linked)
+  return linked && warning
+    ? `The herdr plugin link to ${linked.root} is stale (${warning}); not relinked from a lane worktree, run sync outside one.`
+    : null
+}
+
+/** Whether the package root lies below a `node_modules` directory, i.e. was installed rather than checked out. */
+export const isInstalledCopy = (packageRoot: string): boolean => packageRoot.split(/[\\/]/).includes('node_modules')
+
+type Listing = { missing: boolean; linked: LinkedPlugin | null; legacyLinked: boolean }
+
+/**
+ * The plugin herdr lists and whether the old id is linked beside it; null and false when the list failed or has
+ * another shape: then the link is simply made and nothing is unlinked.
+ */
+const listedPlugin = (run: HerdrRun, legacyId: string): Listing => {
+  const listing = run(['plugin', 'list', '--json'])
+  if (listing.missing || listing.exitCode !== 0) return { missing: listing.missing, linked: null, legacyLinked: false }
+  try {
+    const legacyLinked = legacyId !== HERDR_PLUGIN_ID && linkedPluginOf(listing.output, legacyId) !== null
+    return { missing: false, linked: linkedPluginOf(listing.output), legacyLinked }
+  } catch {
+    return { missing: false, linked: null, legacyLinked: false }
+  }
+}
+
+/** Unlinks the old id once the current one is linked; the line to print. */
+const unlinkLegacy = (run: HerdrRun, legacyId: string): string => {
+  const result = run(['plugin', 'unlink', legacyId])
+  return result.exitCode === 0
+    ? `Unlinked the herdr plugin ${legacyId}, which the new one replaces.`
+    : `Could not unlink the old herdr plugin ${legacyId}, herdr said: ${result.output || `exit ${result.exitCode}`}`
+}
+
+const joinLines = (...lines: (string | null)[]): string | null => {
+  const present = lines.filter((line): line is string => line !== null)
+  return present.length > 0 ? present.join('\n') : null
+}
+
+/**
+ * Hooks the kit's herdr plugin into herdr when `init` or `sync` runs inside herdr (`HERDR_ENV=1`), and links it
+ * again when herdr's link points at another directory or herdr cannot read its manifest (`herdr plugin link`
+ * replaces a plugin of the same id). What each copy may link:
+ * - a checkout takes over any link, so a repository that develops the kit keeps its link;
+ * - an installed package only replaces a missing or unreadable link and leaves a working one standing, also one to
+ *   another installed package: otherwise the global package and a project's dependency would take it from each other;
+ * - a lane's worktree never links, since its path goes away with the lane, and only names a broken link.
+ * Returns the line to print, or null when there is nothing to say. A failed link is a hint in the returned line,
+ * never an error: herdr is optional.
+ */
+export const linkHerdrPlugin = ({
+  packageRoot,
+  env,
+  run,
+  copy,
+  legacyPluginId = LEGACY_HERDR_PLUGIN_ID,
+}: LinkRequest): string | null => {
+  if (env.HERDR_ENV !== '1') return null
+  const { missing, linked, legacyLinked } = listedPlugin(run, legacyPluginId)
+  if (missing || copy === PACKAGE_COPY.laneWorktree) return missing ? null : laneNote(linked, packageRoot)
+  const unlink = () => (legacyLinked ? unlinkLegacy(run, legacyPluginId) : null)
+  const directory = join(packageRoot, HERDR_PLUGIN_DIRECTORY)
+  const reason = relinkReasonOf(linked, directory)
+  if (reason === null) return unlink()
+  if (copy === PACKAGE_COPY.installed && reason === RELINK_REASON.elsewhere) return null
+  const result = run(['plugin', 'link', directory])
+  if (result.exitCode !== 0)
+    return `Could not link the herdr plugin, herdr said: ${result.output || `exit ${result.exitCode}`}`
+  const linkedLine = linked
+    ? `Relinked the herdr plugin from ${linked.root} to ${directory} (${reasonText(reason, linked)}).`
+    : 'Linked the herdr plugin (the pane and the action for the plans view).'
+  return joinLines(linkedLine, unlink())
+}
+
+/** herdr as `HerdrRun`: the binary of `herdrBinary`, run without a shell. */
+const spawnHerdr =
+  (env: Record<string, string | undefined>): HerdrRun =>
+  (args) =>
+    spawnTool(env)(herdrBinary(env), args)
+
+const realPathOf = (path: string): string => {
+  try {
+    return realpathSync(path)
+  } catch {
+    return path
+  }
+}
+
+/** A lane's worktree first, so a package installed into one never links either; a workspace link resolves to its checkout. */
+const packageCopyOf = (packageRoot: string): PackageCopy => {
+  if (isLinkedWorktree(packageRoot)) return PACKAGE_COPY.laneWorktree
+  return isInstalledCopy(realPathOf(packageRoot)) ? PACKAGE_COPY.installed : PACKAGE_COPY.checkout
+}
+
+export const linkHerdrPluginFrom = (packageRoot: string): string | null =>
+  linkHerdrPlugin({
+    packageRoot,
+    env: process.env,
+    run: spawnHerdr(process.env),
+    copy: packageCopyOf(packageRoot),
+  })

package/src/sync/if-changed.ts

@@ -0,0 +1,109 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { LEGACY_MANIFEST_PATH } from '../config/legacy-names'
+import { MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
+import { CLI_NAME, isNewerVersion, PACKAGE_NAME } from '../version/release'
+import { parseManifest } from './manifest'
+import { FILE_MODE } from './plan-file'
+import { assertOwnDirectoriesInProject, writeFileSafely } from './project-fs'
+
+/** When the npm registry was last asked for a newer version, in epoch milliseconds. */
+export type UpdateState = { checkedAt: number }
+
+/** How `--if-changed` learns the time and the newest version on npm; null when npm gave no answer. */
+export type UpdateCheck = { now: () => number; latestVersion: () => Promise<string | null> }
+
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+const REGISTRY_LATEST = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`
+const REGISTRY_TIMEOUT_MS = 3_000
+const UPDATE_STATE_FILE = 'update-check.json'
+
+/**
+ * A sync is due when the installed package is not the version the global lock was written by. Without a lock
+ * there is no global install to keep current: that takes `init --global`, never a hook.
+ */
+export const syncNeeded = (installed: string, locked: string | null): boolean => locked !== null && installed !== locked
+
+/** npm is asked at most once a day; a check stamped in the future (a clock set back) does not block it. */
+export const updateCheckDue = (state: UpdateState | null, now: number): boolean =>
+  state === null || state.checkedAt > now || now - state.checkedAt >= UPDATE_CHECK_INTERVAL_MS
+
+/**
+ * The line a `SessionStart` hook hands the session as context when npm has a newer release. It tells the session
+ * to ask the user through a dialog before running `jh update`; the hook installs nothing itself. Only
+ * a plain release version is interpolated, since this text becomes part of the session's prompt.
+ */
+export const updateNotice = (latest: string | null, installed: string): string | null =>
+  latest && isNewerVersion(latest, installed)
+    ? `${CLI_NAME} ${latest} is on npm, ${installed} is installed. Ask the user with AskUserQuestion whether to run \`${CLI_NAME} update\` now (update now / not now), and run it only after a yes.`
+    : null
+
+const readJson = async (path: string): Promise<unknown> => {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+const versionOfLock = async (path: string): Promise<string | null> => {
+  const parsed = parseManifest(await readJson(path))
+  return parsed.ok ? parsed.manifest.kitVersion : null
+}
+
+/** The kit version the global lock was written by, under its old name while the global sync has not moved it. */
+export const lockedVersion = async (home: string): Promise<string | null> =>
+  (await versionOfLock(join(home, TOOL_DIRECTORY, MANIFEST_FILE))) ?? versionOfLock(join(home, LEGACY_MANIFEST_PATH))
+
+const readUpdateState = async (path: string): Promise<UpdateState | null> => {
+  const raw = await readJson(path)
+  const checkedAt = typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>).checkedAt : undefined
+  return typeof checkedAt === 'number' ? { checkedAt } : null
+}
+
+/** Stamps the check without following a link at `~/.jackherd` or the file; false when it was refused. */
+const stampUpdateCheck = async (home: string, now: number): Promise<boolean> => {
+  try {
+    await assertOwnDirectoriesInProject(home)
+    await writeFileSafely(
+      join(home, TOOL_DIRECTORY),
+      UPDATE_STATE_FILE,
+      `${JSON.stringify({ checkedAt: now })}\n`,
+      FILE_MODE.regular,
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The update line, when the daily check is due and npm has a newer release. The check is stamped before npm is
+ * asked, so a registry that does not answer is asked again tomorrow, not in every session.
+ */
+export const dailyUpdateNotice = async (
+  home: string,
+  installed: string,
+  check: UpdateCheck,
+): Promise<string | null> => {
+  const path = join(home, TOOL_DIRECTORY, UPDATE_STATE_FILE)
+  const now = check.now()
+  if (!updateCheckDue(await readUpdateState(path), now)) return null
+  if (!(await stampUpdateCheck(home, now))) return null
+  return updateNotice(await check.latestVersion(), installed)
+}
+
+/** Asks the npm registry for the `latest` tag; null on any failure, after a few seconds at most. */
+const registryLatestVersion = async (): Promise<string | null> => {
+  try {
+    const response = await fetch(REGISTRY_LATEST, { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) })
+    if (!response.ok) return null
+    const { version } = (await response.json()) as { version?: unknown }
+    return typeof version === 'string' ? version : null
+  } catch {
+    return null
+  }
+}
+
+export const defaultUpdateCheck = (): UpdateCheck => ({ now: () => Date.now(), latestVersion: registryLatestVersion })