jackherd 0.0.1 → 1.0.0

package/herdr-plugin/herdr-plugin.toml

@@ -0,0 +1,22 @@
+id = "crossdelta.jackherd"
+name = "jackherd"
+version = "1.0.0"
+min_herdr_version = "0.8.2"
+description = "Show the plans of a board's lanes in a herdr pane"
+platforms = ["linux", "macos"]
+
+[[panes]]
+id = "plans"
+title = "jackherd plans"
+placement = "split"
+command = ["bunx", "jackherd", "plans"]
+
+[[actions]]
+id = "open-plans"
+title = "Open the plans view"
+description = "Split the focused pane to the right and run jh plans there, in the focused pane's directory"
+contexts = ["workspace"]
+command = ["bun", "open-plans.ts"]
+
+[[startup]]
+command = ["bun", "restore-plans.ts"]

package/herdr-plugin/open-plans.ts

@@ -0,0 +1,43 @@
+import { spawnSync } from 'node:child_process'
+
+export const PLUGIN_ID = 'crossdelta.jackherd'
+
+export const PLANS_PANE = 'plans'
+
+/** The directory herdr reports for a pane in the JSON answer of `herdr pane get`, null when it names none. */
+export const paneDirectoryOf = (json: string): string | null => {
+  try {
+    const cwd = (JSON.parse(json) as { result?: { pane?: { cwd?: unknown } } }).result?.pane?.cwd
+    return typeof cwd === 'string' && cwd !== '' ? cwd : null
+  } catch {
+    return null
+  }
+}
+
+/** Arguments of `herdr plugin pane open` for the plans pane: to the right of the pane, in its directory when known. */
+export const openPlansArguments = (pane: string | null, directory: string | null): string[] => [
+  'plugin',
+  'pane',
+  'open',
+  '--plugin',
+  PLUGIN_ID,
+  '--entrypoint',
+  PLANS_PANE,
+  '--placement',
+  'split',
+  '--direction',
+  'right',
+  ...(pane ? ['--target-pane', pane] : []),
+  ...(directory ? ['--cwd', directory] : []),
+  '--focus',
+]
+
+const main = (): number => {
+  const herdr = process.env.HERDR_BIN_PATH || 'herdr'
+  const pane = process.env.HERDR_PANE_ID || null
+  const answer = pane ? spawnSync(herdr, ['pane', 'get', pane], { encoding: 'utf-8' }) : null
+  const directory = answer?.status === 0 ? paneDirectoryOf(answer.stdout) : null
+  return spawnSync(herdr, openPlansArguments(pane, directory), { stdio: 'inherit' }).status ?? 1
+}
+
+if (import.meta.main) process.exitCode = main()

package/herdr-plugin/restore-plans.ts

@@ -0,0 +1,107 @@
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+
+type Limits = { attempts: number; intervalMs: number }
+
+/**
+ * Measured on herdr 0.9.0: the hook starts ~85 ms after the server, `pane process-info` answers
+ * `pane_not_found` until the terminals spawn at ~0.9 s, and the agents are back at ~3 s. The panes get 10 s, ten
+ * times what they took; `plans --ensure` gets four tries 2 s apart, past the ~3 s of the agents, for a pane that
+ * goes away between the two reads.
+ */
+export const RESTORE_LIMITS = {
+  panes: { attempts: 20, intervalMs: 500 },
+  ensure: { attempts: 4, intervalMs: 2_000 },
+} as const satisfies Record<string, Limits>
+
+/** Runs `attempt` until it works or the attempts are used up, waiting the interval between two of them. */
+export const retried = (attempt: () => boolean, limits: Limits, sleep: (ms: number) => void): boolean => {
+  for (let tried = 1; ; tried++) {
+    if (attempt()) return true
+    if (tried >= limits.attempts) return false
+    sleep(limits.intervalMs)
+  }
+}
+
+/**
+ * The directories of the panes an agent runs in, each once, from a `herdr pane list` answer; none when unreadable.
+ * `agentPanes` are the panes of `herdr agent list`: right after a restart the pane list names no agent there for a
+ * few seconds.
+ */
+export const agentDirectoriesOf = (json: string, agentPanes: readonly string[]): string[] => {
+  try {
+    const panes = (JSON.parse(json) as { result?: { panes?: unknown } }).result?.panes
+    if (!Array.isArray(panes)) return []
+    const directories = panes.flatMap((pane) => {
+      const { cwd, agent, pane_id } = (pane ?? {}) as { cwd?: unknown; agent?: unknown; pane_id?: unknown }
+      const hasAgent = typeof agent === 'string' || (typeof pane_id === 'string' && agentPanes.includes(pane_id))
+      return typeof cwd === 'string' && hasAgent ? [cwd] : []
+    })
+    return [...new Set(directories)]
+  } catch {
+    return []
+  }
+}
+
+/** The arguments for `bun` that run `plans --ensure` with the CLI of the package this plugin ships in. */
+export const ensureArguments = (pluginRoot: string): string[] => [
+  join(dirname(pluginRoot), 'src', 'cli.ts'),
+  'plans',
+  '--ensure',
+]
+
+const idsOf = (json: string, key: 'panes' | 'agents'): string[] => {
+  try {
+    const entries = (JSON.parse(json) as { result?: Record<string, unknown> }).result?.[key]
+    if (!Array.isArray(entries)) return []
+    return entries.flatMap((entry) => {
+      const id = (entry as { pane_id?: unknown } | null)?.pane_id
+      return typeof id === 'string' ? [id] : []
+    })
+  } catch {
+    return []
+  }
+}
+
+const mainCheckoutOf = (directory: string): string | null => {
+  const answer = spawnSync('git', ['-C', directory, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    encoding: 'utf-8',
+  })
+  return answer.status === 0 ? dirname(answer.stdout.trim()) : null
+}
+
+const herdrRun = (args: string[]) =>
+  spawnSync(process.env.HERDR_BIN_PATH || 'herdr', args, { encoding: 'utf-8' })
+
+/** Whether herdr answers `process-info` for every pane, which it does only once their terminals run. */
+const panesAnswer = (panes: readonly string[]): boolean =>
+  panes.every((pane) => herdrRun(['pane', 'process-info', '--pane', pane]).status === 0)
+
+const ensureIn = (root: string, pluginRoot: string): boolean =>
+  spawnSync('bun', ensureArguments(pluginRoot), { cwd: root, stdio: 'inherit' }).status === 0
+
+/**
+ * herdr's `[[startup]]` hook: after a server start or a live handoff, brings back the plans views of every
+ * repository an agent runs in. It parses herdr's answers itself and never throws, unlike the strict parsers of
+ * `src/plans/plan-panes.ts`: a hook that fails leaves nothing behind but a log line, and `plans --ensure`, which it
+ * calls, reads the panes again strictly. It reads the panes at once, while herdr still names their agents, then waits until
+ * herdr answers for every pane and retries `plans --ensure` within `RESTORE_LIMITS`. A repository without a board
+ * or config only prints why and is skipped.
+ */
+const main = (): number => {
+  const list = herdrRun(['pane', 'list'])
+  if (list.status !== 0) console.error(`restore-plans: herdr pane list failed: ${list.stderr || list.status}`)
+  const listing = list.stdout ?? ''
+  const directories = agentDirectoriesOf(listing, idsOf(herdrRun(['agent', 'list']).stdout ?? '', 'agents'))
+  const roots = new Set(directories.flatMap((directory) => mainCheckoutOf(directory) ?? []))
+  if (roots.size === 0) return 0
+  const sleep = (ms: number) => Bun.sleepSync(ms)
+  if (!retried(() => panesAnswer(idsOf(listing, 'panes')), RESTORE_LIMITS.panes, sleep))
+    console.error('restore-plans: herdr did not answer for every pane in time, trying anyway')
+  for (const root of roots)
+    if (!retried(() => ensureIn(root, import.meta.dir), RESTORE_LIMITS.ensure, sleep))
+      console.error(`restore-plans: plans --ensure failed in ${root}`)
+  return 0
+}
+
+if (import.meta.main) process.exitCode = main()

package/install.sh

@@ -0,0 +1,157 @@
+#!/bin/sh
+# Installs jackherd for Claude Code: Bun only if it is missing, then the kit, then its setup wizard.
+#
+#   curl -fsSL https://unpkg.com/jackherd/install.sh | sh
+#
+# Never as root, no edits to shell files: the official Bun installer puts Bun into ~/.bun and says
+# itself which shell file it changed. Every action is announced on one line before it runs.
+set -eu
+
+# The default is the version this file ships with. The release bump changes it together with
+# package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.0.0}"
+
+JACKHERD_PACKAGE='jackherd'
+# Test seam: the terminal the wizard asks its questions on.
+JACKHERD_TEST_TTY="${JACKHERD_TEST_TTY:-/dev/tty}"
+BUN_INSTALLER_URL='https://bun.com/install'
+BUN_MIN_MAJOR=1
+BUN_MIN_MINOR=3
+
+say() {
+  printf 'jackherd install: %s\n' "$1"
+}
+
+fail() {
+  printf 'jackherd install: %s\n' "$1" >&2
+  exit 1
+}
+
+# Digits and exactly two inner dots: major.minor.patch, nothing a shell or npm could read differently.
+is_release() {
+  case $1 in
+    '' | *[!0-9.]* | .* | *. | *..* | *.*.*.*) return 1 ;;
+    *.*.*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+is_number() {
+  case $1 in
+    '' | *[!0-9]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+check_platform() {
+  os=$(uname -s)
+  case $os in
+    Linux | Darwin) ;;
+    *) fail "unsupported system '$os': this installer runs on Linux and macOS only" ;;
+  esac
+}
+
+bun_bin_dir() {
+  printf '%s/bin\n' "${BUN_INSTALL:-$HOME/.bun}"
+}
+
+# The bun on PATH, else the one the official installer leaves in ~/.bun/bin; empty when there is none.
+find_bun() {
+  if command -v bun >/dev/null 2>&1; then
+    command -v bun
+  elif [ -x "$(bun_bin_dir)/bun" ]; then
+    printf '%s\n' "$(bun_bin_dir)/bun"
+  fi
+}
+
+require_bun_installer_tools() {
+  missing=''
+  for tool in curl unzip bash; do
+    command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"
+  done
+  [ -z "$missing" ] || fail "Bun is missing, and installing it needs:$missing. Install them and run this again."
+}
+
+install_bun() {
+  require_bun_installer_tools
+  installer=$(mktemp) || fail "could not create a temporary file"
+  trap 'rm -f "$installer"' EXIT
+  # A trapped signal would otherwise let the script carry on; exiting runs the EXIT trap above.
+  trap 'exit 1' INT TERM HUP
+  say "Bun not found, downloading the official installer from $BUN_INSTALLER_URL"
+  curl --proto '=https' --tlsv1.2 -fsSL "$BUN_INSTALLER_URL" -o "$installer" || fail "could not download $BUN_INSTALLER_URL"
+  say "running the Bun installer (installs into $(bun_bin_dir), without root)"
+  bash "$installer" || fail "the Bun installer failed"
+  [ -x "$(bun_bin_dir)/bun" ] || fail "the Bun installer finished, but $(bun_bin_dir)/bun is missing"
+}
+
+check_bun_version() {
+  version=$("$1" --version) || fail "could not run '$1 --version'"
+  major=${version%%.*}
+  rest=${version#*.}
+  minor=${rest%%.*}
+  if ! is_number "$major" || ! is_number "$minor"; then
+    fail "could not read the Bun version '$version'"
+  fi
+  if [ "$major" -lt "$BUN_MIN_MAJOR" ] || { [ "$major" -eq "$BUN_MIN_MAJOR" ] && [ "$minor" -lt "$BUN_MIN_MINOR" ]; }; then
+    fail "Bun $version is too old, jackherd needs $BUN_MIN_MAJOR.$BUN_MIN_MINOR or newer. Update it with 'bun upgrade' and run this again."
+  fi
+  say "using Bun $version ($1)"
+}
+
+# Bun's global bin, not whatever jh comes first on PATH: an older install elsewhere stays untouched.
+jh_bin() {
+  global_bin=$("$1" pm bin -g) || fail "could not read Bun's global bin ('bun pm bin -g')"
+  [ -x "$global_bin/jh" ] || fail "jh is not in Bun's global bin ($global_bin) after the install"
+  printf '%s\n' "$global_bin/jh"
+}
+
+# Opening it is the test: under 'curl | sh' stdin is the script, and /dev/tty may exist without a terminal.
+terminal_available() {
+  (: <"$JACKHERD_TEST_TTY") 2>/dev/null
+}
+
+run_setup() {
+  if terminal_available; then
+    say "starting the setup: jh init --global"
+    "$1" init --global <"$JACKHERD_TEST_TTY" || fail "jh init --global failed"
+  else
+    say "no terminal to ask questions on, setting up with the defaults: jh init --global --yes"
+    "$1" init --global --yes </dev/null || fail "jh init --global --yes failed"
+  fi
+}
+
+main() {
+  [ "$(id -u)" -ne 0 ] || fail "run this as your own user, not as root (no sudo)"
+  is_release "$JACKHERD_VERSION" || fail "JACKHERD_VERSION must be a plain release like 1.2.3, not '$JACKHERD_VERSION'"
+  [ -n "${HOME:-}" ] || fail "HOME is not set"
+  check_platform
+  # Bun reads bunfig.toml (registry, preload, global bin) from the working directory; one in the
+  # directory this was started from must not steer the install. 'init --global' writes to ~ only.
+  cd "$HOME" || fail "could not change into HOME ($HOME)"
+
+  bun=$(find_bun)
+  if [ -z "$bun" ]; then
+    install_bun
+    bun="$(bun_bin_dir)/bun"
+  fi
+  case $bun in
+    /*) ;;
+    *) fail "found bun at '$bun', expected an absolute path" ;;
+  esac
+  check_bun_version "$bun"
+  # This run only: the kit's CLI starts with '#!/usr/bin/env bun'.
+  PATH="$(dirname "$bun"):$PATH"
+  export PATH
+
+  spec="$JACKHERD_PACKAGE@$JACKHERD_VERSION"
+  say "installing $spec: bun add -g --ignore-scripts $spec"
+  "$bun" add -g --ignore-scripts "$spec" || fail "bun add -g failed"
+
+  # An assignment, so a failure inside the substitution stops the run (set -e) instead of passing on ''.
+  jh=$(jh_bin "$bun")
+  run_setup "$jh"
+  say "done"
+}
+
+main