jackherd 0.0.1 → 1.0.1

package/src/terminal/text.ts

@@ -0,0 +1,159 @@
+import { takeCells, textWidth } from './width'
+
+export const ESC = '\x1b'
+const SGR_PATTERN = `${ESC}\\[[0-9;]*m`
+const LINK_TERMINATOR = `(?:${ESC}\\\\|\\x07)`
+const LINK_START_PATTERN = `${ESC}\\]8;[^;${ESC}\\x07]*;[^${ESC}\\x07]+${LINK_TERMINATOR}`
+const LINK_END_PATTERN = `${ESC}\\]8;;${LINK_TERMINATOR}`
+const ANSI_PATTERN = `${SGR_PATTERN}|${LINK_START_PATTERN}|${LINK_END_PATTERN}`
+const ANSI = new RegExp(ANSI_PATTERN, 'g')
+const ANSI_TOKEN = new RegExp(`(${ANSI_PATTERN})`)
+const LINK_START = new RegExp(`^${LINK_START_PATTERN}$`)
+const LINK_END_TOKEN = new RegExp(`^${LINK_END_PATTERN}$`)
+const LINK_CLOSE = `${ESC}]8;;${ESC}\\`
+const LINK = new RegExp(
+  `${ESC}\\]8;[^;${ESC}\\x07]*;([^${ESC}\\x07]+)${LINK_TERMINATOR}([^]*?)${LINK_END_PATTERN}`,
+  'g',
+)
+export const RESET = `${ESC}[0m`
+const ELLIPSIS = '…'
+const BAR_START = `${ESC}[27;32m`
+const BAR_REST = `${ESC}[39;2m`
+export const BAR_SEGMENT = new RegExp(`${ESC}\\[27;32m[^${ESC}]*${ESC}\\[39;2m[^${ESC}]*${ESC}\\[0m`, 'g')
+export const INVERSE_ON = `${ESC}[7m`
+/**
+ * A badge's background and text in 256 colours: grey (240) with white (255) for every link, amber (136) with dark
+ * text (16) for something new to read, dark red (124) with white for something that blocks a merge. Each sets its
+ * own background, so it reads the same on light and dark terminals.
+ */
+export const BADGE_TONE = { grey: '48;5;240;38;5;255', amber: '48;5;136;38;5;16', red: '48;5;124;38;5;255' } as const
+
+export type BadgeTone = (typeof BADGE_TONE)[keyof typeof BADGE_TONE]
+const FAINT_ON = `${ESC}[2m`
+const FAINT_OFF = `${ESC}[22m`
+const BAR_WIDTH = 10
+
+const style = (code: string) => (text: string) => `${ESC}[${code}m${text}${RESET}`
+export const paint = {
+  bold: style('1'),
+  dim: style('2'),
+  red: style('31'),
+  green: style('32'),
+  yellow: style('33'),
+  magenta: style('35'),
+  cyan: style('36'),
+  inverse: style('7'),
+}
+
+export const stripAnsi = (text: string): string => text.replace(ANSI, '')
+
+const isPrintableAscii = (text: string): boolean =>
+  [...text].every((character) => {
+    const code = character.charCodeAt(0)
+    return code >= 0x20 && code <= 0x7e
+  })
+
+/**
+ * `text` as an OSC 8 hyperlink; a terminal without support shows the bare text. A URL with a byte outside printable
+ * ASCII (OSC 8 allows no other) could end the sequence early and write its own, so it yields no link at all.
+ */
+export const link = (url: string, text: string): string =>
+  isPrintableAscii(url) ? `${ESC}]8;;${url}${ESC}\\${text}${LINK_CLOSE}` : text
+
+/**
+ * `text` as a badge: a background of `tone` (grey unless given) with a cell of padding either side, the text linked
+ * to `url`, and `hint` after it, faint.
+ */
+export const badge = (url: string, text: string, hint = '', tone: BadgeTone = BADGE_TONE.grey): string =>
+  `${ESC}[${tone}m ${link(url, text)}${hint ? `${FAINT_ON} ${hint}${FAINT_OFF}` : ''} ${RESET}`
+
+/** A line for output that is not a terminal: styling dropped, each link written out as `text (url)`. */
+export const plainText = (text: string): string =>
+  stripAnsi(text.replace(LINK, (_, url, inner) => `${stripAnsi(inner)} (${url})`))
+
+/** The terminal cells a styled line takes: emoji count two. */
+export const visibleLength = (text: string): number => textWidth(stripAnsi(text))
+
+/** Cuts a styled line to `width` visible characters, ending in `…` when something was cut. */
+export const fit = (line: string, width: number): string => {
+  if (visibleLength(line) <= width) return line
+  const tokens = line.split(ANSI_TOKEN)
+  let budget = width - 1
+  let result = ''
+  let linkOpen = false
+  for (const token of tokens) {
+    if (token.startsWith(ESC)) {
+      result += token
+      if (LINK_START.test(token)) linkOpen = true
+      else if (LINK_END_TOKEN.test(token)) linkOpen = false
+      continue
+    }
+    result += takeCells(token, Math.max(budget, 0))
+    budget -= textWidth(token)
+  }
+  return `${result}${linkOpen ? LINK_CLOSE : ''}${ELLIPSIS}${RESET}`
+}
+
+/** Left and right part on one line; when both do not fit, the left part is cut, never the right. */
+export const spread = (left: string, right: string, width: number): string => {
+  if (!right) return fit(left, width)
+  const room = width - visibleLength(right) - 1
+  if (room < 1) return fit(right, width)
+  const shown = fit(left, room)
+  return `${shown}${' '.repeat(width - visibleLength(shown) - visibleLength(right))}${right}`
+}
+
+/** A progress bar that is full only when everything is ticked: 38 of 40 shows nine blocks, not ten. */
+export const bar = (done: number, total: number, width = BAR_WIDTH): string => {
+  const complete = total > 0 && done === total
+  const filled = complete ? width : total === 0 ? 0 : Math.floor((done / total) * width)
+  return `${BAR_START}${'█'.repeat(filled)}${BAR_REST}${'░'.repeat(width - filled)}${RESET}`
+}
+
+const chunk = (word: string, width: number): string[] => {
+  const chunks: string[] = []
+  for (let rest = word; rest.length > 0; rest = rest.slice(chunks[chunks.length - 1].length)) {
+    chunks.push(takeCells(rest, width) || String.fromCodePoint(rest.codePointAt(0) ?? 0))
+  }
+  return chunks
+}
+
+/**
+ * Groups `cells` greedily into lines of at most `room` cells, `gap` between neighbours. A cell that does not
+ * fit beside the last one starts a line; `split` may break a cell that is wider than a line into several.
+ */
+export const packGroups = (
+  cells: string[],
+  room: number,
+  gap: string,
+  split: (cell: string) => string[] = (cell) => [cell],
+): string[][] => {
+  const groups: string[][] = []
+  const widths: number[] = []
+  for (const cell of cells) {
+    const width = visibleLength(cell)
+    const last = groups.length - 1
+    if (last >= 0 && widths[last] + gap.length + width <= room) {
+      groups[last].push(cell)
+      widths[last] += gap.length + width
+      continue
+    }
+    for (const part of split(cell)) {
+      groups.push([part])
+      widths.push(visibleLength(part))
+    }
+  }
+  return groups
+}
+
+export const pack = (cells: string[], room: number, gap: string, split?: (cell: string) => string[]): string[] =>
+  packGroups(cells, room, gap, split).map((group) => group.join(gap))
+
+/** Breaks plain text into lines of at most `width` characters, at spaces where it can. */
+export const wrap = (text: string, width: number): string[] =>
+  pack(text.split(' '), width, ' ', (word) => chunk(word, width))
+
+export const padVisible = (text: string, width: number): string =>
+  `${text}${' '.repeat(Math.max(width - visibleLength(text), 0))}`
+
+export const indented = (lines: string[], indent: string): string[] => lines.map((line) => `${indent}${line}`)

package/src/terminal/types.ts

@@ -0,0 +1,30 @@
+/** The agent states a terminal adapter reports; adapters deliver them as plain strings. */
+export const AGENT_STATUS = { working: 'working', blocked: 'blocked', done: 'done', idle: 'idle' } as const
+
+export type AgentStatus = (typeof AGENT_STATUS)[keyof typeof AGENT_STATUS]
+
+export const isAgentStatus = (value: string): value is AgentStatus =>
+  (Object.values(AGENT_STATUS) as string[]).includes(value)
+
+/** A name to list the unnamed agent of one pane under. */
+export type AdoptedName = { pane: string; name: string }
+
+/**
+ * One agent as a terminal adapter reports it; `pane` identifies where its sidebar title is set, `session` is the
+ * id of its Claude Code session (the name of its log), null when the terminal does not say. `cwd` is the directory the agent runs in.
+ */
+export type LaneAgent = { name: string; pane: string; status: string; session: string | null; cwd: string | null }
+
+/**
+ * Where lane agents run. The plans view reads agent status and sets a short title per lane through
+ * this; the adapter `none` stands for a setup without a terminal multiplexer.
+ */
+export type LaneStatusSource = {
+  /**
+   * Throws with the reason when the terminal cannot be asked, so the screen can say why lanes show no agent.
+   * An agent without a name is left out, except the one in `adopt.pane`, which is listed under `adopt.name`.
+   */
+  listAgents: (adopt?: AdoptedName) => LaneAgent[]
+  /** Sets, or with null clears, the title of a pane. Returns the error text, or null on success. */
+  setTitle: (pane: string, title: string | null) => string | null
+}

package/src/terminal/width.ts

@@ -0,0 +1,90 @@
+const VARIATION_SELECTOR = 0xfe0f
+const ZERO_WIDTH_JOINER = 0x200d
+const COMBINING_MARKS: readonly [number, number][] = [[0x0300, 0x036f]]
+
+/** Wide in East Asian Width, or emoji by default presentation: a terminal draws these in two cells. */
+const WIDE: readonly [number, number][] = [
+  [0x1100, 0x115f],
+  [0x231a, 0x231b],
+  [0x23e9, 0x23ec],
+  [0x23f0, 0x23f0],
+  [0x23f3, 0x23f3],
+  [0x25fd, 0x25fe],
+  [0x2614, 0x2615],
+  [0x2648, 0x2653],
+  [0x267f, 0x267f],
+  [0x2693, 0x2693],
+  [0x26a1, 0x26a1],
+  [0x26aa, 0x26ab],
+  [0x26bd, 0x26be],
+  [0x26c4, 0x26c5],
+  [0x26ce, 0x26ce],
+  [0x26d4, 0x26d4],
+  [0x26ea, 0x26ea],
+  [0x26f2, 0x26f3],
+  [0x26f5, 0x26f5],
+  [0x26fa, 0x26fa],
+  [0x26fd, 0x26fd],
+  [0x2705, 0x2705],
+  [0x270a, 0x270b],
+  [0x2728, 0x2728],
+  [0x274c, 0x274c],
+  [0x274e, 0x274e],
+  [0x2753, 0x2755],
+  [0x2757, 0x2757],
+  [0x2795, 0x2797],
+  [0x27b0, 0x27b0],
+  [0x27bf, 0x27bf],
+  [0x2b1b, 0x2b1c],
+  [0x2b50, 0x2b50],
+  [0x2b55, 0x2b55],
+  [0x2e80, 0xa4cf],
+  [0xac00, 0xd7a3],
+  [0xf900, 0xfaff],
+  [0xfe30, 0xfe6f],
+  [0xff00, 0xff60],
+  [0xffe0, 0xffe6],
+  [0x1f300, 0x1f64f],
+  [0x1f680, 0x1f6ff],
+  [0x1f900, 0x1f9ff],
+  [0x20000, 0x3fffd],
+]
+
+const within = (ranges: readonly [number, number][], codePoint: number): boolean =>
+  ranges.some(([from, to]) => codePoint >= from && codePoint <= to)
+
+/**
+ * The terminal cells one code point takes: 0 for variation selectors, joiners and combining marks, 2 for
+ * wide characters and emoji in emoji presentation, 1 otherwise. A symbol that is emoji only with a
+ * variation selector (`⏸`) is one cell on its own; `textWidth` counts it as two when the selector follows.
+ */
+export const cellWidth = (codePoint: number): number => {
+  if (codePoint === VARIATION_SELECTOR || codePoint === ZERO_WIDTH_JOINER) return 0
+  if (within(COMBINING_MARKS, codePoint)) return 0
+  return within(WIDE, codePoint) ? 2 : 1
+}
+
+const characterWidth = (character: string, next: string | undefined): number => {
+  const width = cellWidth(character.codePointAt(0) ?? 0)
+  return next?.codePointAt(0) === VARIATION_SELECTOR && width === 1 ? 2 : width
+}
+
+/** The cells a text takes; an emoji followed by a variation selector takes two. */
+export const textWidth = (text: string): number => {
+  const characters = [...text]
+  return characters.reduce((sum, character, index) => sum + characterWidth(character, characters[index + 1]), 0)
+}
+
+/** The longest start of `text` that fits `width` cells; a wide character that would cross the edge stays out. */
+export const takeCells = (text: string, width: number): string => {
+  const characters = [...text]
+  let used = 0
+  let count = 0
+  for (const [index, character] of characters.entries()) {
+    const next = characterWidth(character, characters[index + 1])
+    if (used + next > width) break
+    used += next
+    count = index + 1
+  }
+  return characters.slice(0, count).join('')
+}

package/src/update/command.ts

@@ -0,0 +1,65 @@
+/**
+ * `jh update`: installs the newest release with the package manager that holds the kit globally,
+ * then syncs `~/.claude` (and the project, when the working directory is inside one) with the new code. It
+ * runs only when the user or a session that asked the user starts it; no hook runs it.
+ *
+ *   jh update
+ */
+import { existsSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { findProjectRoot } from '../config/location'
+import { defaultUpdateCheck, lockedVersion } from '../sync/if-changed'
+import { locateKit } from '../sync/kit-source'
+import { readInstalledVersion } from '../version/installed-version'
+import { CLI_NAME } from '../version/release'
+import { detectPackageManager, legacyPackageRoot } from './package-manager'
+import { runUpdate, UPDATE_EXIT, type UpdateAdapters } from './update'
+
+const USAGE = `Usage: ${CLI_NAME} update`
+
+/** Runs `argv` without a shell and with the terminal attached, so the manager's own output stays visible. */
+const runInherited = async (argv: readonly string[], cwd: string): Promise<number> => {
+  try {
+    const child = Bun.spawn([...argv], {
+      cwd: cwd ?? undefined,
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+    return await child.exited
+  } catch {
+    return UPDATE_EXIT.error
+  }
+}
+
+const adaptersFor = async (): Promise<UpdateAdapters> => {
+  const { version, packageRoot } = await locateKit()
+  const home = homedir()
+  return {
+    installedVersion: version,
+    manager: detectPackageManager(realpathSync(packageRoot)),
+    latestVersion: defaultUpdateCheck().latestVersion,
+    installedVersionOnDisk: () => readInstalledVersion(packageRoot),
+    kitCli: [process.execPath, join(packageRoot, 'src', 'cli.ts')],
+    run: runInherited,
+    hasGlobalKit: async () => (await lockedVersion(home)) !== null,
+    hasLegacyPackage: () => existsSync(legacyPackageRoot(realpathSync(packageRoot))),
+    home,
+    projectRoot: findProjectRoot(process.cwd(), home, existsSync),
+    log: (line) => console.log(line),
+  }
+}
+
+export const run = async (args: string[]): Promise<number> => {
+  if (args.length > 0) {
+    console.log(USAGE)
+    return UPDATE_EXIT.error
+  }
+  try {
+    return await runUpdate(await adaptersFor())
+  } catch (error) {
+    console.log(`${CLI_NAME} update failed: ${error instanceof Error ? error.message : String(error)}`)
+    return UPDATE_EXIT.error
+  }
+}

package/src/update/package-manager.ts

@@ -0,0 +1,56 @@
+import { dirname, join } from 'node:path'
+import { isRelease, PACKAGE_NAME } from '../version/release'
+
+export const PACKAGE_MANAGER = { bun: 'bun', npm: 'npm', pnpm: 'pnpm', yarn: 'yarn' } as const
+
+export type PackageManager = (typeof PACKAGE_MANAGER)[keyof typeof PACKAGE_MANAGER]
+
+/** The package's name before the rename; `jh update` names how to remove it, never removes it itself. */
+export const LEGACY_PACKAGE_NAME = '@crossdelta/agent-kit'
+
+/** Where each manager keeps its global packages; the first match decides, npm's `lib/node_modules` last. */
+const GLOBAL_LOCATIONS: readonly (readonly [RegExp, PackageManager])[] = [
+  [/\/\.bun\/install\/global\//, PACKAGE_MANAGER.bun],
+  [/\/pnpm\/global\/|\/\.pnpm-global\//, PACKAGE_MANAGER.pnpm],
+  [/\/yarn\/global\/|\/\.yarn\/global\//, PACKAGE_MANAGER.yarn],
+  [/\/lib\/node_modules\//, PACKAGE_MANAGER.npm],
+]
+
+/**
+ * The manager that installed the kit globally, read from where the package lies; null for a project
+ * dependency or a source checkout, which `jh update` does not touch.
+ */
+export const detectPackageManager = (packageRoot: string): PackageManager | null => {
+  const path = `${packageRoot.replaceAll('\\', '/')}/`
+  return GLOBAL_LOCATIONS.find(([pattern]) => pattern.test(path))?.[1] ?? null
+}
+
+/**
+ * The argv, never a shell line, that installs `version` globally without running install scripts: the kit
+ * has none and a dependency's would run before the new code is looked at. Throws unless `version` is a plain release.
+ */
+export const installCommand = (manager: PackageManager, version: string): string[] => {
+  if (!isRelease(version)) throw new Error(`Refusing to install "${version}": not a plain release version`)
+  const spec = `${PACKAGE_NAME}@${version}`
+  const verbs: Record<PackageManager, string[]> = {
+    [PACKAGE_MANAGER.bun]: ['bun', 'add', '-g'],
+    [PACKAGE_MANAGER.npm]: ['npm', 'install', '-g'],
+    [PACKAGE_MANAGER.pnpm]: ['pnpm', 'add', '-g'],
+    [PACKAGE_MANAGER.yarn]: ['yarn', 'global', 'add'],
+  }
+  return [...verbs[manager], '--ignore-scripts', spec]
+}
+
+/** The argv that removes the global package `name` with `manager`. */
+export const removeCommand = (manager: PackageManager, name: string): string[] => {
+  const verbs: Record<PackageManager, string[]> = {
+    [PACKAGE_MANAGER.bun]: ['bun', 'remove', '-g'],
+    [PACKAGE_MANAGER.npm]: ['npm', 'uninstall', '-g'],
+    [PACKAGE_MANAGER.pnpm]: ['pnpm', 'remove', '-g'],
+    [PACKAGE_MANAGER.yarn]: ['yarn', 'global', 'remove'],
+  }
+  return [...verbs[manager], name]
+}
+
+/** Where the package before the rename lies when the same manager installed it: beside this one. */
+export const legacyPackageRoot = (packageRoot: string): string => join(dirname(packageRoot), LEGACY_PACKAGE_NAME)

package/src/update/update.ts

@@ -0,0 +1,105 @@
+import { CLI_NAME, isNewerVersion, isRelease } from '../version/release'
+import { installCommand, LEGACY_PACKAGE_NAME, type PackageManager, removeCommand } from './package-manager'
+
+export const UPDATE_EXIT = { ok: 0, error: 1 } as const
+
+/** Everything `jh update` touches outside itself, so a test runs it without a registry or an install. */
+export type UpdateAdapters = {
+  installedVersion: string
+  /** The manager that installed the kit globally, or null when it is not a global install. */
+  manager: PackageManager | null
+  latestVersion: () => Promise<string | null>
+  /** The version in the package on disk now, after the install; null when it cannot be read. */
+  installedVersionOnDisk: () => string | null
+  /** The words that start this very package's CLI (runtime, then `src/cli.ts`), so a sync runs the code just installed and no `jh` found on the path. */
+  kitCli: readonly string[]
+  /** Runs one command without a shell, in `cwd`, and returns its exit code. */
+  run: (argv: readonly string[], cwd: string) => Promise<number>
+  hasGlobalKit: () => Promise<boolean>
+  /** True when the package before the rename is installed globally beside this one. */
+  hasLegacyPackage: () => boolean
+  home: string
+  /** The project the working directory belongs to, or null. */
+  projectRoot: string | null
+  log: (line: string) => void
+}
+
+const notGlobalLine = (installed: string): string =>
+  `${CLI_NAME} ${installed} is not a global install (a project dependency or a source checkout), so \`${CLI_NAME} update\` leaves it alone. Update it with the package manager of that project.`
+
+const failed = (log: UpdateAdapters['log'], step: string, command: string): number => {
+  log(`${CLI_NAME} update: ${step} failed. Run it by hand: ${command}`)
+  return UPDATE_EXIT.error
+}
+
+/** The syncs that bring `~/.claude` and the project to the new files, in the order they run. */
+const syncSteps = async (adapters: UpdateAdapters): Promise<{ argv: string[]; cwd: string }[]> => [
+  ...((await adapters.hasGlobalKit()) ? [{ argv: [...adapters.kitCli, 'sync', '--global'], cwd: adapters.home }] : []),
+  ...(adapters.projectRoot ? [{ argv: [...adapters.kitCli, 'sync'], cwd: adapters.projectRoot }] : []),
+]
+
+/**
+ * Installs `version` from the home directory, so the working directory's package-manager configuration cannot
+ * point the install at another registry, and checks the package on disk is that version afterwards.
+ */
+const installAndVerify = async (
+  adapters: UpdateAdapters,
+  manager: PackageManager,
+  version: string,
+): Promise<number> => {
+  const install = installCommand(manager, version)
+  if ((await adapters.run(install, adapters.home)) !== 0) return failed(adapters.log, 'the install', install.join(' '))
+  const onDisk = adapters.installedVersionOnDisk()
+  if (onDisk === version) return UPDATE_EXIT.ok
+  adapters.log(
+    `${CLI_NAME} update: the install ran, but the version on disk is still ${onDisk ?? 'unreadable'}, not ${version}.`,
+  )
+  return UPDATE_EXIT.error
+}
+
+/**
+ * The update itself: installs the newest release, then runs the syncs with the freshly installed code. Does
+ * nothing when no newer release exists. The version it
+ * installs is the one it checked, and only a plain release reaches the command line.
+ */
+const updateToLatest = async (adapters: UpdateAdapters, manager: PackageManager): Promise<number> => {
+  const { installedVersion, log } = adapters
+  const latest = await adapters.latestVersion()
+  if (latest === null) {
+    log(`${CLI_NAME} update: the npm registry did not answer, nothing was changed.`)
+    return UPDATE_EXIT.error
+  }
+  if (!isRelease(latest)) {
+    log(`${CLI_NAME} update: the npm registry answered no plain release version, nothing was changed.`)
+    return UPDATE_EXIT.error
+  }
+  if (!isNewerVersion(latest, installedVersion)) {
+    log(`${CLI_NAME} ${installedVersion} is the latest release.`)
+    return UPDATE_EXIT.ok
+  }
+  const installed = await installAndVerify(adapters, manager, latest)
+  if (installed !== UPDATE_EXIT.ok) return installed
+  for (const { argv, cwd } of await syncSteps(adapters)) {
+    if ((await adapters.run(argv, cwd)) !== 0) return failed(log, 'the sync', argv.join(' '))
+  }
+  log(`${CLI_NAME} updated ${installedVersion} → ${latest}.`)
+  return UPDATE_EXIT.ok
+}
+
+const legacyPackageLine = (manager: PackageManager): string =>
+  `${LEGACY_PACKAGE_NAME} is still installed globally; ${CLI_NAME} replaces it. Remove it with: ${removeCommand(manager, LEGACY_PACKAGE_NAME).join(' ')}`
+
+/**
+ * Installs the newest release with the manager that holds the kit globally, then syncs `~/.claude` and the
+ * project with the freshly installed code; a global package from before the rename is named, not removed.
+ */
+export const runUpdate = async (adapters: UpdateAdapters): Promise<number> => {
+  const { manager, log } = adapters
+  if (!manager) {
+    log(notGlobalLine(adapters.installedVersion))
+    return UPDATE_EXIT.error
+  }
+  const exitCode = await updateToLatest(adapters, manager)
+  if (exitCode === UPDATE_EXIT.ok && adapters.hasLegacyPackage()) log(legacyPackageLine(manager))
+  return exitCode
+}

package/src/version/installed-version.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isRelease } from './release'
+import type { StartedKit } from './started-kit'
+
+export type KitUpdate = { from: string; to: string }
+
+/** How often a long-running process looks at the package on disk. */
+export const VERSION_POLL_MS = 10_000
+
+/**
+ * The version in the package at `packageRoot` now; null when it cannot be read or is no plain release.
+ * A reinstall replaces the directory, so a miss during it is normal and means "ask again later".
+ */
+export const readInstalledVersion = (packageRoot: string): string | null => {
+  try {
+    const { version } = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')) as { version?: unknown }
+    return typeof version === 'string' && isRelease(version) ? version : null
+  } catch {
+    return null
+  }
+}
+
+/** The update a running process has not loaded yet: the version on disk differs from the one it started with. */
+export const kitUpdate = (startedWith: string, onDisk: string | null): KitUpdate | null =>
+  onDisk !== null && onDisk !== startedWith ? { from: startedWith, to: onDisk } : null
+
+/** The update a process has not loaded yet, read from the disk now; null without a located kit. */
+export const pendingKitUpdate = (kit: StartedKit | null): KitUpdate | null =>
+  kit ? kitUpdate(kit.version, readInstalledVersion(kit.packageRoot)) : null
+
+export const kitUpdatedLine = ({ from, to }: KitUpdate): string => `=== kit updated ${from} → ${to}`

package/src/version/release.ts

@@ -0,0 +1,22 @@
+export const PACKAGE_NAME = 'jackherd'
+
+/** The command the package installs; every usage text and message names it through this. */
+export const CLI_NAME = 'jh'
+
+const RELEASE = /^(\d+)\.(\d+)\.(\d+)$/
+
+const releaseParts = (version: string): number[] | null => {
+  const match = RELEASE.exec(version)
+  return match ? match.slice(1).map(Number) : null
+}
+
+/** True when `version` is a plain `major.minor.patch` release, the only shape that may reach a command line or a prompt. */
+export const isRelease = (version: string): boolean => RELEASE.test(version)
+
+/** True when `candidate` is a release (no pre-release) above `installed`. */
+export const isNewerVersion = (candidate: string, installed: string): boolean => {
+  const [next, current] = [releaseParts(candidate), releaseParts(installed)]
+  if (!next || !current) return false
+  const index = next.findIndex((part, position) => part !== current[position])
+  return index !== -1 && next[index] > current[index]
+}

package/src/version/skill-diff.ts

@@ -0,0 +1,63 @@
+/** What the watcher can say about the orchestrate skill after a kit update. */
+export const SKILL_CHANGE = { changed: 'changed', unchanged: 'unchanged', unavailable: 'unavailable' } as const
+
+export type SkillChange =
+  | { kind: typeof SKILL_CHANGE.changed; sections: string[]; diffPath: string }
+  | { kind: typeof SKILL_CHANGE.unchanged }
+  | { kind: typeof SKILL_CHANGE.unavailable; reason: string }
+
+const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/
+const SECTION_HEADING = /^## (.+)$/
+const NUMBERED_SECTION = /^(\d+)\.\s/
+const HEAD = 'head'
+
+/**
+ * The lines of the new text that changed, 1-based: an added line where it stands, a removed line at the place it
+ * left. Context lines only move the count.
+ */
+const changedLines = (diff: string): number[] => {
+  const lines: number[] = []
+  let next = 0
+  for (const line of diff.split('\n')) {
+    const header = line.match(HUNK_HEADER)
+    if (header) {
+      next = Number(header[1])
+      continue
+    }
+    if (next === 0 || line.startsWith('\\')) continue
+    if (line.startsWith('-')) lines.push(next)
+    else if (line.startsWith('+')) lines.push(next++)
+    else next++
+  }
+  return lines
+}
+
+const sectionLabel = (heading: string): string => {
+  const numbered = heading.match(NUMBERED_SECTION)
+  return numbered ? `§ ${numbered[1]}` : heading.trim()
+}
+
+/** For each line of `text`, the `## ` section it belongs to; `head` before the first one. */
+const sectionOfLines = (text: string): string[] => {
+  let current = HEAD
+  return text.split('\n').map((line) => {
+    const heading = line.match(SECTION_HEADING)
+    if (heading?.[1]) current = sectionLabel(heading[1])
+    return current
+  })
+}
+
+/** The sections of the new skill text whose lines a unified diff adds or removes, once each, in order. */
+export const changedSections = (text: string, diff: string): string[] => {
+  const sections = sectionOfLines(text)
+  const touched = changedLines(diff).map((line) => sections[Math.min(line, sections.length) - 1] ?? HEAD)
+  return [...new Set(touched)]
+}
+
+export const skillChangeLine = (change: SkillChange): string => {
+  if (change.kind === SKILL_CHANGE.changed) {
+    return `orchestrate skill: ${change.sections.join(', ')} changed · diff ${change.diffPath}`
+  }
+  if (change.kind === SKILL_CHANGE.unchanged) return 'orchestrate skill unchanged'
+  return `orchestrate skill diff unavailable (${change.reason}): read the skill again`
+}

package/src/version/started-kit.ts

@@ -0,0 +1,14 @@
+import { locateKit } from '../sync/kit-source'
+import { isRelease } from './release'
+
+export type StartedKit = { packageRoot: string; version: string }
+
+/** The kit this process loaded: where it lies and which version; null when the package cannot be located or its version is no plain release. */
+export const startedKit = async (): Promise<StartedKit | null> => {
+  try {
+    const { packageRoot, version } = await locateKit()
+    return isRelease(version) ? { packageRoot, version } : null
+  } catch {
+    return null
+  }
+}