docks-kit 0.1.0 → 0.1.2

package/lib/skills.sh

@@ -1,373 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-# Source-order guards: this lib depends on common.sh's log/warn/err and on
-# the entry script's REPO_DIR. Fail fast with a clear message if sourced standalone.
-declare -F log >/dev/null 2>&1 || { printf '\033[1;31m[err]\033[0m %s\n' "lib/skills.sh must be sourced after lib/common.sh" >&2; exit 1; }
-[[ -n "${REPO_DIR:-}" ]] || { printf '\033[1;31m[err]\033[0m %s\n' "REPO_DIR must be set before sourcing lib/skills.sh" >&2; exit 1; }
-
-# Universal AI-agent skills bootstrap (agentskills.io standard).
-# Reads SoT/.agents/skills.txt, runs `npx skills add` for each missing slug.
-# Idempotent: pre-checks ~/.agents/skills/<basename> and skips if present.
-
-skills::sync() {
-  # AGENTS_DIR is initialized in lib/common.sh as a kit-global with env override.
-  # The kit installs each skill for claude-code + codex (its SoT support
-  # matrix). Naming two agents makes the CLI keep the canonical copy at the
-  # universal ~/.agents/skills/ path — that's what our checks track.
-  SKILLS_DIR="$AGENTS_DIR/skills"
-  SKILLS_MANIFEST="$REPO_DIR/SoT/.agents/skills.txt"
-  SKILLS_SNAPSHOT="$AGENTS_DIR/.kit-managed-skills"
-  SKILLS_SYNCED=1
-
-  [[ -f "$SKILLS_MANIFEST" ]] || return
-
-  # A fresh machine may not have ~/.agents/skills/ yet; create it so the
-  # pre-check below has a dir to stat (the CLI also creates it on install).
-  [[ "$DRY_RUN" -eq 1 ]] || mkdir -p "$SKILLS_DIR"
-
-  skills::sync_universal
-  if [[ "$PRUNE" -eq 1 ]]; then
-    skills::reconcile_removals
-  fi
-  skills::sync_agent_browser_cli
-  skills::sync_effect_solutions_cli
-  skills::update_snapshot
-}
-
-# The `skills` npm package spec for npx invocations, pinned to the manifest's
-# verified version (supply-chain: never run a floating @latest CLI every sync).
-skills::_skills_cli() {
-  local v
-  v="$(toolchain::field skills-cli verified 2>/dev/null || true)"
-  printf '%s' "skills${v:+@$v}"
-}
-
-# Emit one cleaned slug per line from a manifest: skip blank/comment lines, strip
-# inline #comments and ALL whitespace. Single source of truth so sync_universal,
-# _load_slug_list, and update_snapshot can never diverge on parsing.
-skills::_normalize_manifest() {
-  awk '
-    /^[[:space:]]*#/ { next }
-    /^[[:space:]]*$/ { next }
-    { sub(/[[:space:]]*#.*$/, ""); gsub(/[[:space:]]+/, ""); if (length($0)) print }
-  ' "$1"
-}
-
-skills::sync_universal() {
-  local slug basename added=0 already=0 failed=0 healed=0
-
-  if ! command -v node >/dev/null 2>&1; then
-    warn "node/npx not in PATH — skipping universal skills bootstrap (install Node.js to enable)"
-    return
-  fi
-
-  # DRY_RUN branches only at the action point, so dry-run and real see the same
-  # normalized slug set from skills::_normalize_manifest.
-  while IFS= read -r slug; do
-    basename="${slug##*/}"
-
-    if [[ "$DRY_RUN" -eq 1 ]]; then
-      if [[ -d "$SKILLS_DIR/$basename" ]]; then
-        echo "[dry-run] universal skill present: $basename"
-        skills::heal_claude_symlink "$basename" || true
-      else
-        echo "[dry-run] npx $(skills::_skills_cli) add $slug -g -y -a claude-code codex"
-      fi
-      continue
-    fi
-
-    if [[ -d "$SKILLS_DIR/$basename" ]]; then
-      already=$((already + 1))
-      if skills::heal_claude_symlink "$basename"; then
-        healed=$((healed + 1))
-      fi
-      continue
-    fi
-
-    # <source> is positional and MUST precede the variadic -a/--agent flag,
-    # or --agent swallows the slug. Naming both agents (claude-code codex)
-    # makes the CLI keep the canonical ~/.agents/skills/ copy and symlink it
-    # into ~/.claude/skills/; a single agent would copy-direct instead.
-    if npx --yes "$(skills::_skills_cli)" add "$slug" -g -y -a claude-code codex >/dev/null 2>&1; then
-      added=$((added + 1))
-    else
-      warn "Failed to install universal skill: $slug"
-      failed=$((failed + 1))
-    fi
-  done < <(skills::_normalize_manifest "$SKILLS_MANIFEST")
-
-  [[ "$DRY_RUN" -eq 1 ]] && return
-
-  SKILLS_PRESENT=$((added + already))
-
-  if [[ "$added" -gt 0 ]]; then
-    log "Universal skills synced (+$added new, $already already present)"
-  else
-    log "Universal skills already in sync ($already present)"
-  fi
-  if [[ "$healed" -gt 0 ]]; then
-    log "Claude per-tool symlinks healed (+$healed) — canonical present, ~/.claude/skills/<name> was missing or broken"
-  fi
-  if [[ "$failed" -gt 0 ]]; then
-    warn "$failed skill install(s) failed — re-run sync or install manually with: npx skills add <slug> -g -y -a claude-code codex"
-  fi
-}
-
-# Recreate ~/.claude/skills/<basename> → ../../.agents/skills/<basename>
-# when canonical exists but the per-tool symlink is missing or broken.
-# Matches the relative path the upstream `skills` CLI writes
-# (vercel-labs/skills installer.ts:createSymlink uses relative(parentDir, target)).
-# Idempotent: leaves correct symlinks alone; replaces stale/broken symlinks.
-# Skips real (non-symlink) directories to avoid destroying user content.
-# Returns 0 when a heal occurred, 1 otherwise (so callers can tally).
-skills::heal_claude_symlink() {
-  local basename="$1"
-  local canonical="$SKILLS_DIR/$basename"
-  local claude_skills_dir="$HOME/.claude/skills"
-  local claude_link="$claude_skills_dir/$basename"
-  local rel_target="../../.agents/skills/$basename"
-
-  [[ -d "$canonical" ]] || return 1
-
-  if [[ -L "$claude_link" ]]; then
-    local current
-    current="$(readlink "$claude_link" 2>/dev/null || true)"
-    if [[ "$current" == "$rel_target" ]]; then
-      return 1
-    fi
-    if [[ "$DRY_RUN" -eq 1 ]]; then
-      echo "[dry-run] would replace stale Claude symlink: ~/.claude/skills/$basename -> $current  (correct: $rel_target)"
-      return 0
-    fi
-    rm -f "$claude_link"
-  elif [[ -e "$claude_link" ]]; then
-    warn "~/.claude/skills/$basename exists as a real path (not a symlink) — leaving alone; remove manually if it's stale"
-    return 1
-  else
-    if [[ "$DRY_RUN" -eq 1 ]]; then
-      echo "[dry-run] would create missing Claude symlink: ~/.claude/skills/$basename -> $rel_target"
-      return 0
-    fi
-  fi
-
-  mkdir -p "$claude_skills_dir"
-  ln -s "$rel_target" "$claude_link"
-  return 0
-}
-
-# toolchain::ensure callback for agent-browser. Upgrade = npm refresh only (the
-# Chrome download is not repeated); first install also pulls Chrome for Testing.
-skills::_agent_browser_install() {
-  local mode="$1" version="${2:-}" verb="Installing"
-  [[ "$mode" == "upgrade" ]] && verb="Upgrading"
-  local pkg="agent-browser${version:+@$version}"
-  local install_flags=()
-  case "$(uname -s)" in
-    Linux*) install_flags+=(--with-deps) ;;  # may prompt sudo for libnss3/libatk
-  esac
-
-  log "$verb agent-browser CLI via npm${version:+ (pinned $version)}..."
-  if ! npm install -g "$pkg" >/dev/null 2>&1; then
-    warn "npm install -g $pkg failed. Try manually: npm install -g $pkg"
-    return 1
-  fi
-
-  if [[ "$mode" == "install" ]]; then
-    log "Downloading Chrome for Testing (~175 MB; sudo may be requested for system libs on Linux)..."
-    if ! agent-browser install ${install_flags[@]+"${install_flags[@]}"}; then
-      warn "agent-browser install failed. Re-run manually: agent-browser install ${install_flags[*]:-}"
-      return 1
-    fi
-  fi
-  log "agent-browser CLI ready ($(agent-browser --version 2>/dev/null | awk '{print $NF}' || echo 'version unknown'))"
-}
-
-skills::sync_agent_browser_cli() {
-  # The agent-browser SKILL.md alone is just instructions — the CLI binary
-  # is what drives Chrome. Auto-install on first run because the slug is
-  # declared in skills.txt (declaration = "I want this on every machine").
-  grep -q '^vercel-labs/agent-browser$' "$SKILLS_MANIFEST" 2>/dev/null || return 0
-
-  if ! command -v npm >/dev/null 2>&1; then
-    [[ "$DRY_RUN" -eq 1 ]] || warn "npm not found — cannot auto-install agent-browser CLI. Install Node.js, then re-run sync."
-    return
-  fi
-
-  # `|| warn`: a failed npm install must not abort the remaining skills sync
-  # (snapshot write, effect-solutions) under set -e.
-  toolchain::ensure agent-browser skills::_agent_browser_install || warn "agent-browser bootstrap failed — continuing sync"
-}
-
-# Resolve a usable `bun` binary. `bun` lives in ~/.bun/bin, which is off the
-# non-interactive PATH that sync/agent shells use, so `command -v` alone misses
-# a perfectly good install. Fall back to the known install locations.
-skills::_find_bun() {
-  local c
-  c="$(command -v bun 2>/dev/null || true)"
-  [[ -n "$c" ]] && { printf '%s\n' "$c"; return 0; }
-  for c in "${BUN_INSTALL:-$HOME/.bun}/bin/bun" "$HOME/.bun/bin/bun"; do
-    [[ -x "$c" ]] && { printf '%s\n' "$c"; return 0; }
-  done
-  return 1
-}
-
-# effect-solutions is the optional ground-truth Effect docs CLI the effect-kit
-# skills consult opportunistically. It ships as a Bun bin with a
-# `#!/usr/bin/env bun` shebang, so BOTH `bun` and the CLI must be on PATH to
-# run it. bun's global bin (~/.cache/.bun/bin or ~/.bun/bin, depending on
-# BUN_INSTALL/XDG_CACHE_HOME) and bun itself sit off the non-interactive PATH,
-# and ~/.bashrc's "if not interactive, return" guard means rc PATH edits never
-# reach agent shells. So we symlink both binaries into ~/.local/bin — already
-# first on the agent PATH, matching Codex's official standalone install path. Gated on
-# effect-kit being enabled in SoT; auto-installs Bun when absent (download-
-# then-run, per the kit's no-`curl|bash` rule).
-# Bootstrap Bun itself (download-then-run, per the kit's no-`curl|bash` rule).
-# Echoes the bun path on success. Shared toolchain callback material: also used
-# directly when only Bun is missing.
-skills::_bun_bootstrap() {
-  local bun tmp_bun_installer pin
-  if bun="$(skills::_find_bun)"; then
-    printf '%s\n' "$bun"
-    return 0
-  fi
-  if ! command -v curl >/dev/null 2>&1; then
-    warn "Bun and curl both missing — cannot bootstrap Bun. Install Bun manually, then re-run sync."
-    return 1
-  fi
-  # The installer takes a release tag (bun-vX.Y.Z) as $1 — install the
-  # kit-verified version, not floating latest.
-  pin="$(toolchain::field bun verified 2>/dev/null || true)"
-  warn "Bun not found — installing Bun${pin:+ $pin (kit-verified)}..."
-  tmp_bun_installer=$(mktemp 2>/dev/null || echo "/tmp/bun-install-$$.sh")
-  curl -fsSL https://bun.sh/install -o "$tmp_bun_installer" \
-    && bash "$tmp_bun_installer" ${pin:+"bun-v$pin"} >/dev/null 2>&1 || true
-  rm -f "$tmp_bun_installer"
-  if ! bun="$(skills::_find_bun)"; then
-    warn "Bun install failed. Install manually: curl -fsSL https://bun.sh/install -o /tmp/bun.sh && bash /tmp/bun.sh"
-    return 1
-  fi
-  log "Bun installed ($("$bun" --version 2>/dev/null || echo 'version unknown'))"
-  printf '%s\n' "$bun"
-}
-
-# toolchain::ensure callback for effect-solutions: install and upgrade are the
-# same idempotent `bun add -g effect-solutions@<version>` (the gate-approved
-# version arrives as $2) — the toolchain `track` policy is what finally gives
-# this CLI the self-upgrade that agent-browser always had.
-skills::_effect_solutions_install() {
-  local mode="$1" version="${2:-}" verb="Installing"
-  [[ "$mode" == "upgrade" ]] && verb="Upgrading"
-  local pkg="effect-solutions@${version:-latest}" bun gbin
-
-  bun="$(skills::_bun_bootstrap)" || return 1
-
-  log "$verb effect-solutions CLI via bun${version:+ (pinned $version)}..."
-  if ! "$bun" add -g "$pkg" >/dev/null 2>&1; then
-    warn "bun add -g $pkg failed. Try manually: bun add -g $pkg"
-    return 1
-  fi
-
-  # `bun pm -g bin` is the authoritative global-bin query (path varies with
-  # BUN_INSTALL/XDG_CACHE_HOME). Link the CLI and bun itself so the shebang
-  # resolves in non-interactive agent shells.
-  gbin="$("$bun" pm -g bin 2>/dev/null || true)"
-  if [[ -n "$gbin" && -x "$gbin/effect-solutions" ]]; then
-    mkdir -p "$HOME/.local/bin"
-    ln -sf "$bun" "$HOME/.local/bin/bun"
-    ln -sf "$gbin/effect-solutions" "$HOME/.local/bin/effect-solutions"
-    log "effect-solutions CLI ready (linked bun + effect-solutions into ~/.local/bin)"
-  else
-    warn "effect-solutions installed but binary not found under '${gbin:-<unknown>}' — link it onto PATH manually"
-  fi
-}
-
-skills::sync_effect_solutions_cli() {
-  local settings="$REPO_DIR/SoT/.claude/settings.json"
-  grep -Eq '"effect-kit@docks"[[:space:]]*:[[:space:]]*true' "$settings" 2>/dev/null || return 0
-
-  toolchain::ensure effect-solutions skills::_effect_solutions_install || warn "effect-solutions bootstrap failed — continuing sync"
-}
-
-# Populate <array_name> with stripped, non-empty slugs from <file>. Supports
-# both manifest format (4-step strip + comment handling) and snapshot format
-# (one slug per line, no comments — strip is a safe no-op).
-skills::_load_slug_list() {
-  local file="$1" array_name="$2" slug
-  while IFS= read -r slug; do
-    eval "$array_name+=(\"\$slug\")"
-  done < <(skills::_normalize_manifest "$file")
-}
-
-# Uninstall a single snapshot slug from the universal CLI. Increments the
-# caller's <ok_var>/<fail_var> via eval (bash 3.2-safe; no namerefs).
-skills::_remove_one_slug() {
-  local slug="$1" ok_var="$2" fail_var="$3" basename="${1##*/}"
-  if [[ "$DRY_RUN" -eq 1 ]]; then
-    echo "[dry-run] kit-managed skill no longer in SoT — would remove: $basename"
-    return
-  fi
-  if npx --yes "$(skills::_skills_cli)" remove --global -y -a '*' -s "$basename" >/dev/null 2>&1; then
-    eval "$ok_var=\$(( \$$ok_var + 1 ))"
-  else
-    warn "Failed to remove kit-managed skill: $basename"
-    eval "$fail_var=\$(( \$$fail_var + 1 ))"
-  fi
-}
-
-skills::reconcile_removals() {
-  # Uninstall kit-managed skills (tracked in $SKILLS_SNAPSHOT) that are no longer
-  # declared in $SKILLS_MANIFEST. Never touches user-installed skills (not in
-  # snapshot) or CLI auto-installed meta-skills like find-skills.
-  local slug removed=0 failed=0
-  local -a current_slugs=()
-  local -a snapshot_slugs=()
-
-  if [[ ! -f "$SKILLS_SNAPSHOT" ]]; then
-    if [[ "$DRY_RUN" -eq 1 ]]; then
-      echo "[dry-run] (--prune) no kit-managed-skills snapshot yet; first real sync writes $SKILLS_SNAPSHOT, then future --prune runs reconcile against it"
-    fi
-    return
-  fi
-
-  skills::_load_slug_list "$SKILLS_MANIFEST" current_slugs
-  skills::_load_slug_list "$SKILLS_SNAPSHOT" snapshot_slugs
-
-  for slug in ${snapshot_slugs[@]+"${snapshot_slugs[@]}"}; do
-    if [[ ${#current_slugs[@]} -gt 0 ]] && printf '%s\n' "${current_slugs[@]}" | grep -qx "$slug"; then
-      continue
-    fi
-    skills::_remove_one_slug "$slug" removed failed
-  done
-
-  if [[ "$removed" -gt 0 ]]; then
-    log "Kit-managed skills removed (-$removed)"
-  fi
-  if [[ "$failed" -gt 0 ]]; then
-    warn "$failed skill remove(s) failed — re-run with --prune or run: npx skills remove -g -y -a '*' -s <name>"
-  fi
-}
-
-skills::update_snapshot() {
-  # Persist the current set of kit-declared slugs so the next --prune
-  # pass can detect removed entries. Format: one slug per line, sorted, stable.
-  [[ "$DRY_RUN" -eq 1 ]] && return
-
-  mkdir -p "$AGENTS_DIR"
-  skills::_normalize_manifest "$SKILLS_MANIFEST" | sort -u > "$SKILLS_SNAPSHOT"
-}
-
-skills::summary() {
-  [[ "${SKILLS_SYNCED:-0}" -eq 1 ]] || return
-  echo "Skills:   ${SKILLS_DIR:-$HOME/.agents/skills}"
-  if [[ "$DRY_RUN" -eq 0 ]]; then
-    # SKILLS_PRESENT comes from skills::sync_universal's own tally; a bare
-    # `find` over ~/.agents/skills/ would also count user-installed skills.
-    echo "          ${SKILLS_PRESENT:-0} universal skill(s) installed"
-  fi
-}
-
-skills::next_steps() {
-  [[ "${SKILLS_SYNCED:-0}" -eq 1 ]] || return
-  echo "Restart Claude Code (and Codex) to discover newly installed universal skills."
-}

package/lib/toolchain.sh

@@ -1,222 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-# Source-order guards: this lib depends on common.sh's log/warn/err and on
-# the entry script's REPO_DIR. Fail fast with a clear message if sourced standalone.
-declare -F log >/dev/null 2>&1 || { printf '\033[1;31m[err]\033[0m %s\n' "lib/toolchain.sh must be sourced after lib/common.sh" >&2; exit 1; }
-[[ -n "${REPO_DIR:-}" ]] || { printf '\033[1;31m[err]\033[0m %s\n' "REPO_DIR must be set before sourcing lib/toolchain.sh" >&2; exit 1; }
-
-# Verified-version-floor layer over the external toolchain (SoT/toolchain.json).
-# The manifest holds DATA (kind/policy/floor/verified/pinnable); this lib owns
-# the generic compare/gate/prompt machinery; tool-specific install commands stay
-# in their owning lib (claude.sh knows rtk, skills.sh knows bun/agent-browser/
-# effect-solutions) and are passed to toolchain::ensure as callbacks.
-
-toolchain::_manifest() { printf '%s' "$REPO_DIR/SoT/toolchain.json"; }
-
-toolchain::field() {
-  local tool="$1" field="$2"
-  jq -r --arg t "$tool" --arg f "$field" '.tools[$t][$f] // empty' "$(toolchain::_manifest)" 2>/dev/null
-}
-
-# Strictly-newer semver-ish compare (numeric per dotted field, like the old
-# skills::_agent_browser_newer_npm) — returns 0 when $1 > $2. Deliberately not
-# `sort -V` (absent on older BSD/macOS sort).
-toolchain::_is_newer() {
-  local a="$1" b="$2" newer
-  [[ -n "$a" && -n "$b" && "$a" != "$b" ]] || return 1
-  newer=$(printf '%s\n%s\n' "$a" "$b" | sort -t. -k1,1n -k2,2n -k3,3n | tail -n1)
-  [[ "$newer" == "$a" ]]
-}
-
-# Presence probe. bun gets install-path fallbacks: it lives off the
-# non-interactive PATH (~/.bun/bin), so `command -v` alone misses real installs.
-toolchain::present() {
-  local tool="$1"
-  case "$tool" in
-    bun) command -v bun >/dev/null 2>&1 || [[ -x "${BUN_INSTALL:-$HOME/.bun}/bin/bun" || -x "$HOME/.bun/bin/bun" ]] ;;
-    *)   command -v "$tool" >/dev/null 2>&1 ;;
-  esac
-}
-
-# Installed version, best-effort; empty when the tool is missing or the version
-# is unparseable (ensure treats present-but-unparseable under `track` as stale
-# and refreshes — self-healing rather than silently never upgrading).
-toolchain::installed_version() {
-  # Every arm is `|| true`-guarded: callers assign via $(...) under
-  # set -e/pipefail, so a no-match grep or failing --version must never
-  # propagate a non-zero status — missing/unparseable just means empty output.
-  local tool="$1" bunbin
-  toolchain::present "$tool" || return 0
-  case "$tool" in
-    rtk)            rtk --version 2>/dev/null | awk '{print $2}' || true ;;
-    claude)         claude --version 2>/dev/null | awk '{print $1}' || true ;;
-    codex)          codex --version 2>/dev/null | awk '{print $NF}' || true ;;
-    bun)            { command -v bun >/dev/null 2>&1 && bun --version || "$HOME/.bun/bin/bun" --version; } 2>/dev/null || true ;;
-    agent-browser)  agent-browser --version 2>/dev/null | awk '{print $NF}' || true ;;
-    effect-solutions)
-      bunbin="$(command -v bun 2>/dev/null || echo "$HOME/.bun/bin/bun")"
-      [[ -x "$bunbin" ]] && "$bunbin" pm -g ls 2>/dev/null | grep -oE 'effect-solutions@[0-9][0-9.]*' | head -1 | cut -d@ -f2 || true ;;
-    node)           node --version 2>/dev/null | sed 's/^v//' || true ;;
-    npm)            npm --version 2>/dev/null || true ;;
-    jq)             jq --version 2>/dev/null | sed 's/^jq-//' || true ;;
-    curl)           curl --version 2>/dev/null | awk 'NR==1{print $2}' || true ;;
-    tsc)            tsc --version 2>/dev/null | awk '{print $2}' || true ;;
-    *)              : ;;
-  esac
-  return 0
-}
-
-# Latest available version for managed tools; empty = unknown/offline (ensure
-# then leaves the installed tool alone). Network calls capped at 5s.
-toolchain::latest_version() {
-  local tool="$1"
-  case "$tool" in
-    rtk)
-      curl -fsSL --max-time 5 "https://api.github.com/repos/rtk-ai/rtk/releases/latest" 2>/dev/null \
-        | jq -r '.tag_name // empty' 2>/dev/null | sed 's/^v//' || true ;;
-    agent-browser|effect-solutions)
-      command -v npm >/dev/null 2>&1 && npm view "$tool" version 2>/dev/null || true ;;
-    *) : ;;
-  esac
-  return 0
-}
-
-# Gate a candidate install/upgrade against the kit-verified version. Echoes the
-# version to install ("" = latest) and returns 0 to proceed, 1 to skip.
-#   mode=install : tool missing — a decline falls back to the pinned `verified`
-#                  when pinnable (the machine still needs the tool)
-#   mode=upgrade : a decline stays on the installed version
-toolchain::_gate() {
-  local tool="$1" mode="$2" latest="$3"
-  local verified pinnable answer
-  verified=$(toolchain::field "$tool" verified)
-  pinnable=$(toolchain::field "$tool" pinnable)
-
-  if [[ -z "$verified" ]] || ! toolchain::_is_newer "$latest" "$verified"; then
-    echo ""; return 0
-  fi
-
-  if [[ "$ASSUME_YES" -eq 1 ]]; then
-    warn "$tool $latest is newer than kit-verified $verified — proceeding (--yes)"
-    echo ""; return 0
-  fi
-
-  if [[ -t 0 ]]; then
-    printf '\033[1;33m[warn]\033[0m %s\n' "$tool $latest is not kit-verified (verified: $verified)." >&2
-    read -r -p "Install $tool $latest anyway? [y/N] " answer
-    case "$answer" in
-      [yY]*) echo ""; return 0 ;;
-    esac
-  fi
-
-  if [[ "$mode" == "install" && "$pinnable" == "true" ]]; then
-    warn "installing kit-verified $tool $verified instead of $latest"
-    echo "$verified"; return 0
-  fi
-  warn "skipping $tool ${mode} (latest $latest is above kit-verified $verified; pass --yes to accept, or update SoT/toolchain.json after testing)"
-  return 1
-}
-
-# Ensure a managed tool per manifest policy. install_fn is called as:
-#   <install_fn> <install|upgrade> <version>   (empty version = latest)
-toolchain::ensure() {
-  local tool="$1" install_fn="$2"
-  local policy installed latest target
-
-  policy=$(toolchain::field "$tool" policy)
-
-  if ! toolchain::present "$tool"; then
-    latest=$(toolchain::latest_version "$tool")
-    if [[ "$DRY_RUN" -eq 1 ]]; then
-      echo "[dry-run] would install $tool (${latest:-latest}, gated by toolchain.json verified pin)"
-      return 0
-    fi
-    if [[ -z "$latest" ]]; then
-      # Latest unknown (offline/rate-limited): the gate can't compare, so an
-      # empty target would install unverified latest. Pin the kit-verified
-      # version when we can; otherwise install latest with an explicit warn.
-      target=$(toolchain::field "$tool" verified)
-      if [[ -n "$target" && "$(toolchain::field "$tool" pinnable)" == "true" ]]; then
-        warn "$tool latest version unknown (offline?) — installing kit-verified $target instead"
-      else
-        target=""
-        warn "$tool latest version unknown (offline?) and not pinnable — installing latest unverified"
-      fi
-    else
-      target=$(toolchain::_gate "$tool" install "$latest") || return 0
-    fi
-    # ${target:-$latest}: install the exact version the gate approved, not a
-    # floating "latest" that may have moved since the check.
-    "$install_fn" install "${target:-$latest}"
-    return $?
-  fi
-
-  installed=$(toolchain::installed_version "$tool")
-
-  if [[ "$policy" != "track" ]]; then
-    [[ "$DRY_RUN" -eq 1 ]] && { echo "[dry-run] $tool present (${installed:-version unknown})"; return 0; }
-    log "$tool present (${installed:-version unknown})"
-    return 0
-  fi
-
-  latest=$(toolchain::latest_version "$tool")
-  if [[ -z "$latest" ]]; then
-    [[ "$DRY_RUN" -eq 1 ]] && { echo "[dry-run] $tool present (${installed:-version unknown}); latest unknown (offline?) — no action"; return 0; }
-    log "$tool present (${installed:-version unknown}; latest unknown — no action)"
-    return 0
-  fi
-
-  # Present but version unparseable → refresh to a known state.
-  if [[ -z "$installed" ]] || toolchain::_is_newer "$latest" "$installed"; then
-    if [[ "$DRY_RUN" -eq 1 ]]; then
-      echo "[dry-run] would upgrade $tool (${installed:-unknown} -> $latest, gated by toolchain.json verified pin)"
-      return 0
-    fi
-    target=$(toolchain::_gate "$tool" upgrade "$latest") || return 0
-    "$install_fn" upgrade "${target:-$latest}"
-    return $?
-  fi
-
-  [[ "$DRY_RUN" -eq 1 ]] && { echo "[dry-run] $tool up to date ($installed)"; return 0; }
-  log "$tool up to date ($installed)"
-}
-
-# Doctor table over every manifest tool (also consumed by `docks-kit status`).
-# Status: ok | missing | below-floor(<floor>) | above-verified(<verified>).
-toolchain::report() {
-  local tool kind os floor verified installed status
-  printf '%-28s %-9s %-14s %-9s %-9s %s\n' "TOOL" "KIND" "INSTALLED" "FLOOR" "VERIFIED" "STATUS"
-  while IFS= read -r tool; do
-    os=$(toolchain::field "$tool" os)
-    if [[ -n "$os" ]]; then
-      case "$(uname -s)" in
-        Linux*)  [[ "$os" == "linux" ]]  || continue ;;
-        Darwin*) [[ "$os" == "darwin" ]] || continue ;;
-      esac
-    fi
-    kind=$(toolchain::field "$tool" kind)
-    floor=$(toolchain::field "$tool" floor)
-    verified=$(toolchain::field "$tool" verified)
-    if [[ "$kind" == "pin" ]]; then
-      # No binary to probe — the tool is invoked via npx at the pinned version.
-      printf '%-28s %-9s %-14s %-9s %-9s %s\n' \
-        "$tool" "$kind" "(npx)" "${floor:--}" "${verified:--}" "pinned"
-      continue
-    fi
-    if toolchain::present "$tool"; then
-      installed=$(toolchain::installed_version "$tool")
-      status="ok"
-      if [[ -n "$floor" && -n "$installed" ]] && toolchain::_is_newer "$floor" "$installed"; then
-        status="below-floor"
-      elif [[ -n "$verified" && -n "$installed" ]] && toolchain::_is_newer "$installed" "$verified"; then
-        status="above-verified"
-      fi
-    else
-      installed="-"
-      status="missing"
-    fi
-    printf '%-28s %-9s %-14s %-9s %-9s %s\n' \
-      "$tool" "${kind:--}" "${installed:-?}" "${floor:--}" "${verified:--}" "$status"
-  done < <(jq -r '.tools | keys[]' "$(toolchain::_manifest)")
-}