holocron/scripts/sync-plugin-content.sh

#!/usr/bin/env bash
set -euo pipefail

# Mirrors each plugin's .apm/{agents,skills,prompts,commands,instructions,extensions,hooks}
# into flat plugin-root directories (agents/, skills/, commands/, instructions/,
# extensions/, hooks.json) -- Claude Code's and GitHub Copilot's plugin loaders
# convention-scan those flat paths at the plugin root; neither has any awareness of
# apm's .apm/ nesting (confirmed via `strings` on the installed claude binary and a
# live `claude --plugin-dir <bundle> -p ...` discoverability test -- see issue #90).
# `apm pack --format plugin` already implements the correct .apm/ -> plugin-convention
# mapping (it's built for distributable bundles under build/, a directory nothing in
# marketplace.json points at); this script reuses that mapping and copies the relevant
# subset back into the plugin root as compiled output -- same status as
# .claude-plugin/plugin.json, never hand-edited when .apm/ is present.
#
# plugin.json, apm.lock.yaml, and .mcp.json from the bundle are deliberately NOT
# copied: .claude-plugin/plugin.json + .github/plugin/plugin.json are already
# generated in-place at the plugin root by a separate apm code path
# (core/plugin_manifest.py, run as part of the same `apm pack` invocation, keyed off
# cwd rather than -o), and .mcp.json is hand-authored at the plugin root per ADR-0015
# (it is not an .apm/ primitive). Real-mode syncs pass --force so that path actually
# refreshes both files from current apm.yml/.apm/ content -- apm pack silently skips
# regenerating an existing plugin.json otherwise ("already exists; skipping plugin.json
# generation"), which would let them go stale after a name/version/description edit.
#
# apm's Copilot-ecosystem plugin.json builder omits mcpServers entirely -- its own
# docstring calls it out-of-schema for Copilot, but this repo's researched Copilot
# plugin schema docs (plugins/kyberforge/docs/research/docs/github-copilot-plugins/
# configuration.md) document mcpServers as valid there. Real-mode syncs re-inject it
# into .github/plugin/plugin.json from the plugin's own .mcp.json after apm pack runs
# (see reinject_mcp_servers below); staleness there, like the rest of plugin.json, is
# only fixed by the next real sync, not detected by --check.
#
# apm pack also writes .claude-plugin/plugin.json and .github/plugin/plugin.json into
# cwd whenever those files don't already exist yet -- regardless of --force -- so
# --check (which must never mutate the real plugin root) never cds into plugin_dir
# directly. It packs a throwaway copy instead (see sync_one's pack_cwd); only that
# copy's manifest files, never the real ones, can get created as a first-write.
#
# hooks.json is only synced when .apm/hooks/ actually produces one -- a plugin with
# no .apm/hooks/ content is left alone even if a root-level hooks.json already exists
# (pre-existing scaffolding outside this script's concern).
#
# tests/ subdirectories (e.g. .apm/skills/<name>/tests/*.bats) are excluded from the
# mirror -- they are dev-time fixtures a plugin host never needs to discover, and several
# reference their own repo root via a hardcoded relative walk-up (e.g.
# `../../../../../../`) sized for the .apm/-nested depth. Mirroring them verbatim would
# duplicate each file one directory level shallower than that walk-up expects, breaking
# the duplicate and double-running the original under any repo-wide bats/test discovery.

usage() {
  echo "Usage: $0 [--check] (--all | <plugin-dir> [<plugin-dir> ...])" >&2
  exit 1
}

CHECK=0
if [[ "${1:-}" == "--check" ]]; then
  CHECK=1
  shift
fi

ALL=0
if [[ "${1:-}" == "--all" ]]; then
  ALL=1
  shift
fi

if [[ "$ALL" -eq 1 ]]; then
  [[ $# -eq 0 ]] || usage
else
  [[ $# -ge 1 ]] || usage
fi

if ! command -v apm &>/dev/null; then
  echo "Error: apm is required but not installed (see kyberforge:apm-install)" >&2
  exit 1
fi

if ! command -v jq &>/dev/null; then
  echo "Error: jq is required but not installed" >&2
  exit 1
fi

# Convention subdirectories apm's plugin exporter can populate from .apm/.
MIRROR_DIRS=(agents skills commands instructions extensions)

FAIL=0
SCRATCH_ROOT="$(mktemp -d)"
trap 'rm -rf "$SCRATCH_ROOT"' EXIT

if [[ "$ALL" -eq 1 ]]; then
  # Derives the plugin list from marketplace.json the same way
  # scripts/check-manifests.sh does, instead of hand-maintaining a duplicate list
  # at every call site (see .pre-commit-config.yaml's check-plugin-content-sync).
  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
  MARKETPLACE="$REPO_ROOT/.claude-plugin/marketplace.json"
  if [[ ! -f "$MARKETPLACE" ]]; then
    echo "Error: --all requires $MARKETPLACE" >&2
    exit 1
  fi
  declare -a plugin_dirs=()
  plugin_count="$(jq '.plugins | length' "$MARKETPLACE")"
  for ((i = 0; i < plugin_count; i++)); do
    source_type="$(jq -r ".plugins[$i].source | type" "$MARKETPLACE")"
    # Remote sources (github, git, npm objects) have no local directory to sync.
    [[ "$source_type" == "string" ]] || continue
    source="$(jq -r ".plugins[$i].source" "$MARKETPLACE")"
    source="${source#./}"
    plugin_dirs+=("$REPO_ROOT/$source")
  done
else
  declare -a plugin_dirs=("$@")
fi

# Fail fast on a basename collision rather than letting two plugin_dir arguments
# silently share (and corrupt) the same $name.log/$name.status/$name.checkcopy
# scratch paths below.
declare -a seen_names=()
for plugin_dir in "${plugin_dirs[@]}"; do
  name="$(basename "${plugin_dir%/}")"
  for seen in ${seen_names[@]+"${seen_names[@]}"}; do
    if [[ "$seen" == "$name" ]]; then
      echo "Error: duplicate plugin basename '$name' among arguments -- scratch paths would collide" >&2
      exit 1
    fi
  done
  seen_names+=("$name")
done

normalize_trailing_newline() {
  # apm's bundle exporter writes hooks.json without a trailing newline, which
  # end-of-file-fixer (pre-commit) would flag on every regeneration -- normalize
  # instead of fighting that hook on every sync.
  printf '%s\n' "$(cat "$1")" >"$2"
}

sync_dir() {
  local plugin_dir="$1" bundle_dir="$2" d="$3"
  local src="$bundle_dir/$d" dst="$plugin_dir/$d"

  if [[ "$CHECK" -eq 1 ]]; then
    if [[ -d "$src" ]]; then
      if [[ ! -d "$dst" ]]; then
        echo "DRIFT $dst: missing (would be created from .apm/)" >&2
        FAIL=1
      elif ! diff -rq -x tests "$src" "$dst" >/dev/null 2>&1; then
        echo "DRIFT $dst: out of sync with .apm/" >&2
        diff -rq -x tests "$src" "$dst" 2>&1 | sed 's/^/    /' >&2
        FAIL=1
      fi
    elif [[ -d "$dst" ]]; then
      echo "DRIFT $dst: stale, no longer produced from .apm/" >&2
      FAIL=1
    fi
    return 0
  fi

  if [[ -d "$src" ]]; then
    rm -rf "$dst"
    mkdir -p "$dst"
    cp -a "$src/." "$dst/"
    find "$dst" -type d -name tests -exec rm -rf {} +
  elif [[ -d "$dst" ]]; then
    rm -rf "$dst"
  fi
}

sync_hooks_json() {
  local plugin_dir="$1" bundle_dir="$2"
  local src="$bundle_dir/hooks.json" dst="$plugin_dir/hooks.json"

  # No .apm/hooks/ content -- hooks.json (if any) is out of scope for this script.
  [[ -f "$src" ]] || return 0

  if [[ "$CHECK" -eq 1 ]]; then
    local normalized_src
    normalized_src="$(mktemp)"
    normalize_trailing_newline "$src" "$normalized_src"
    if [[ ! -f "$dst" ]] || ! diff -q "$normalized_src" "$dst" >/dev/null 2>&1; then
      echo "DRIFT $dst: out of sync with .apm/hooks/" >&2
      FAIL=1
    fi
    rm -f "$normalized_src"
    return 0
  fi

  normalize_trailing_newline "$src" "$dst"
}

reinject_mcp_servers() {
  local plugin_dir="$1"
  local mcp_src="$plugin_dir/.mcp.json" dst="$plugin_dir/.github/plugin/plugin.json"
  [[ -f "$mcp_src" ]] || return 0
  [[ -f "$dst" ]] || return 0

  # Match apm's own Claude-ecosystem plugin.json builder: mcpServers is omitted
  # entirely when the plugin declares none, not written out as an empty object.
  local count
  count="$(jq '(.mcpServers // {}) | length' "$mcp_src")"
  [[ "$count" -gt 0 ]] || return 0

  local tmp
  tmp="$(mktemp)"
  jq --slurpfile mcp "$mcp_src" '.mcpServers = $mcp[0].mcpServers' "$dst" >"$tmp"
  mv "$tmp" "$dst"
}

# Runs entirely inside a backgrounded subshell (see the dispatch loop below), so
# FAIL here is that subshell's own copy -- it never touches the parent's FAIL
# and must be handed back via status_file instead.
sync_one() {
  local plugin_dir="${1%/}" status_file="$2"
  local apm_dir="$plugin_dir/.apm"
  FAIL=0

  if [[ ! -d "$plugin_dir" ]]; then
    echo "FAIL $plugin_dir: plugin directory does not exist" >&2
    FAIL=1
    echo "$FAIL" >"$status_file"
    return 0
  fi

  if [[ ! -d "$apm_dir" ]]; then
    echo "SKIP $plugin_dir: no .apm/ directory" >&2
    echo "$FAIL" >"$status_file"
    return 0
  fi

  local name scratch bundle_dir pack_log pack_cwd
  name="$(basename "$plugin_dir")"
  scratch="$SCRATCH_ROOT/$name"
  mkdir -p "$scratch"
  pack_log="$(mktemp)"

  local force_flag=()
  if [[ "$CHECK" -eq 0 ]]; then
    force_flag=(--force)
    pack_cwd="$plugin_dir"
  else
    pack_cwd="$SCRATCH_ROOT/$name.checkcopy"
    mkdir -p "$pack_cwd"
    cp -a "$plugin_dir/." "$pack_cwd/"
  fi

  if ! (cd "$pack_cwd" && apm pack --format plugin "${force_flag[@]}" -o "$scratch") >"$pack_log" 2>&1; then
    echo "FAIL $plugin_dir: apm pack failed:" >&2
    sed 's/^/    /' "$pack_log" >&2
    rm -f "$pack_log"
    FAIL=1
    echo "$FAIL" >"$status_file"
    return 0
  fi
  rm -f "$pack_log"

  bundle_dir="$(find "$scratch" -mindepth 1 -maxdepth 1 -type d | head -1)"
  if [[ -z "$bundle_dir" ]]; then
    echo "FAIL $plugin_dir: apm pack produced no bundle directory under $scratch" >&2
    FAIL=1
    echo "$FAIL" >"$status_file"
    return 0
  fi

  local d
  for d in "${MIRROR_DIRS[@]}"; do
    sync_dir "$plugin_dir" "$bundle_dir" "$d"
  done
  sync_hooks_json "$plugin_dir" "$bundle_dir"
  if [[ "$CHECK" -eq 0 ]]; then
    reinject_mcp_servers "$plugin_dir"
  fi
  echo "$FAIL" >"$status_file"
}

# Each plugin's `apm pack` is an independent CLI invocation dominated by fixed
# process-startup cost, not by per-plugin work -- run them concurrently rather
# than paying that startup cost N times serially. Output is buffered per plugin
# (not streamed) so concurrent DRIFT/FAIL messages from different plugins never
# interleave; it's flushed in stable $@ order once every job has finished.
#
# Batched (not a rolling pool) because a bounded rolling pool needs `wait -n`,
# which is bash 4.3+ -- tests/run-tests.sh and tests/run-bats.sh in this same repo
# are explicitly bash-3.2-safe, so this script matches their pattern for
# consistency. `getconf` over `nproc` for the same reason: `nproc` doesn't exist
# on macOS.
JOBS_LIMIT="$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)"
running=0
for plugin_dir in "${plugin_dirs[@]}"; do
  name="$(basename "${plugin_dir%/}")"
  (sync_one "$plugin_dir" "$SCRATCH_ROOT/$name.status") >"$SCRATCH_ROOT/$name.log" 2>&1 &
  running=$((running + 1))
  if [[ $running -ge $JOBS_LIMIT ]]; then
    wait
    running=0
  fi
done
wait

for plugin_dir in "${plugin_dirs[@]}"; do
  name="$(basename "${plugin_dir%/}")"
  cat "$SCRATCH_ROOT/$name.log" >&2
  status="$(cat "$SCRATCH_ROOT/$name.status" 2>/dev/null || echo 1)"
  [[ "$status" -ne 0 ]] && FAIL=1
done

if [[ "$FAIL" -ne 0 ]]; then
  if [[ "$CHECK" -eq 1 ]]; then
    if [[ "$ALL" -eq 1 ]]; then
      echo "Plugin content mirror is out of sync with .apm/. Fix: bash scripts/sync-plugin-content.sh --all" >&2
    else
      echo "Plugin content mirror is out of sync with .apm/. Fix: bash scripts/sync-plugin-content.sh $*" >&2
    fi
  fi
  exit 1
fi