docks-kit 0.1.0

package/lib/skills.sh

@@ -0,0 +1,373 @@
+#!/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

@@ -0,0 +1,222 @@
+#!/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)")
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "docks-kit",
+  "version": "0.1.0",
+  "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DocksDocks/public.git"
+  },
+  "bin": {
+    "docks-kit": "cli/src/main.ts"
+  },
+  "files": [
+    "cli/src",
+    "cli/docs",
+    "cli/tsconfig.json",
+    "lib",
+    "SoT",
+    "notification.mp3",
+    "docks-kit",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p cli",
+    "build:binaries": "bash cli/build-binaries.sh"
+  },
+  "dependencies": {
+    "@effect/cli": "0.75.2",
+    "@effect/platform": "0.96.1",
+    "@effect/platform-bun": "0.90.0",
+    "effect": "3.21.4"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.7.2"
+  }
+}