#!/usr/bin/env bash set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" SCRIPT="$REPO_ROOT/scripts/sync-plugin-content.sh" PASS=0 FAIL=0 pass() { echo " PASS: $1"; PASS=$((PASS + 1)); } fail() { echo " FAIL: $1"; FAIL=$((FAIL + 1)); } if ! command -v apm &>/dev/null; then echo "apm not installed -- skipping (see kyberforge:apm-install)" >&2 exit 77 fi # Minimal fixture exercising every mirrored category -- all five of # scripts/sync-plugin-content.sh's MIRROR_DIRS (agents, skills, commands, # instructions, extensions) plus the merged hooks file -- without needing network # access (no apm.yml dependencies). Two deliberately-shaped skill subdirectories: # # skills/hello/tests/ -- a dev-time fixture that must NOT be mirrored # skills/hello/assets/templates/tests/ -- a template asset that MUST be mirrored # # Those two are the same basename at different depths. The exclusion is depth-scoped # for exactly this reason: the real skill-author skill ships a template tree it # scaffolds from, and a depth-agnostic strip amputated it. # # skills/hello/scripts/run.sh is executable so the mode/symlink drift checks have a # real executable to tamper with. make_fixture() { local dir dir="$(mktemp -d)" mkdir -p "$dir/.apm/skills/hello/tests" "$dir/.apm/skills/hello/scripts" \ "$dir/.apm/skills/hello/assets/templates/tests" "$dir/.apm/agents" \ "$dir/.apm/hooks" "$dir/.apm/commands" "$dir/.apm/instructions" \ "$dir/.apm/extensions" cat > "$dir/apm.yml" <<'YAML' name: fixture version: 0.0.1 description: fixture license: MIT type: hybrid targets: - claude dependencies: apm: [] mcp: [] includes: auto devDependencies: apm: [] scripts: {} YAML cat > "$dir/.apm/skills/hello/SKILL.md" <<'EOF' --- name: hello description: hello --- Hello. EOF cat > "$dir/.apm/skills/hello/tests/sample.bats" <<'EOF' @test "dummy" { true; } EOF cat > "$dir/.apm/skills/hello/assets/templates/tests/README.md" <<'EOF' Template asset: scaffolded into a new skill, not a dev fixture of this one. EOF cat > "$dir/.apm/skills/hello/scripts/run.sh" <<'EOF' #!/usr/bin/env bash echo hi EOF chmod +x "$dir/.apm/skills/hello/scripts/run.sh" cat > "$dir/.apm/agents/foo.agent.md" <<'EOF' --- name: foo description: foo --- Foo. EOF cat > "$dir/.apm/commands/mycmd.md" <<'EOF' --- description: mycmd --- Do a thing. EOF cat > "$dir/.apm/instructions/style.instructions.md" <<'EOF' --- applyTo: "**" --- Be consistent. EOF cat > "$dir/.apm/extensions/thing.md" <<'EOF' Extension content. EOF cat > "$dir/.apm/hooks/hooks.json" <<'EOF' {"hooks": {"PreToolUse": []}} EOF echo "$dir" } # Same base fixture, but with a copilot target (so apm pack produces # .github/plugin/plugin.json) and a caller-supplied .mcp.json -- for exercising # reinject_mcp_servers(). make_fixture_with_mcp() { local mcp_json="$1" dir dir="$(mktemp -d)" mkdir -p "$dir/.apm/skills/hello" "$dir/.apm/agents" cat > "$dir/apm.yml" <<'YAML' name: fixture version: 0.0.1 description: fixture license: MIT type: hybrid targets: - claude - copilot dependencies: apm: [] mcp: [] includes: auto devDependencies: apm: [] scripts: {} YAML cat > "$dir/.apm/skills/hello/SKILL.md" <<'EOF' --- name: hello description: hello --- Hello. EOF cat > "$dir/.apm/agents/foo.agent.md" <<'EOF' --- name: foo description: foo --- Foo. EOF printf '%s' "$mcp_json" > "$dir/.mcp.json" echo "$dir" } CLEANUP_DIRS=() trap 'rm -rf ${CLEANUP_DIRS[@]+"${CLEANUP_DIRS[@]}"}' EXIT track() { CLEANUP_DIRS+=("$1"); } # --- 1. --check reports drift before any sync has run --- echo "" echo "--- --check reports drift on an unsynced fixture ---" FIXTURE="$(make_fixture)"; track "$FIXTURE" if bash "$SCRIPT" --check "$FIXTURE" > /dev/null 2>&1; then fail "exited 0 on an unsynced fixture — expected drift (exit 1)" else pass "exits non-zero (drift) before syncing" fi # --- 2. A real sync creates the flat mirror and exits 0 --- echo "" echo "--- real sync creates every MIRROR_DIRS category plus hooks/hooks.json ---" if bash "$SCRIPT" "$FIXTURE" > /dev/null 2>&1 \ && [[ -f "$FIXTURE/skills/hello/SKILL.md" ]] \ && [[ -f "$FIXTURE/agents/foo.agent.md" ]] \ && [[ -f "$FIXTURE/commands/mycmd.md" ]] \ && [[ -f "$FIXTURE/instructions/style.instructions.md" ]] \ && [[ -f "$FIXTURE/extensions/thing.md" ]] \ && [[ -f "$FIXTURE/hooks/hooks.json" ]]; then pass "sync creates the expected flat mirror for all five MIRROR_DIRS plus hooks/hooks.json" else fail "sync did not create the expected flat mirror" fi # --- 2b. The merged hooks file goes to hooks/hooks.json, never the plugin root --- # Claude Code convention-scans `hooks/hooks.json` at the plugin root (see # plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md's # "Plugin Directory Layout" table, quoted in ADR-0017), and the compiled plugin.json # carries no `hooks` pointer that could redirect it. A root-level hooks.json is read # by nothing. echo "" echo "--- the merged hooks file is not left at the plugin root ---" if [[ ! -e "$FIXTURE/hooks.json" ]]; then pass "no root-level hooks.json after a sync" else fail "sync wrote hooks.json to the plugin root — Claude Code scans hooks/hooks.json" fi # --- 2c. hooks/hooks.json is newline-terminated --- # normalize_trailing_newline() exists so pre-commit's end-of-file-fixer does not # re-dirty the tree on every sync: apm's bundle exporter emits hooks.json with no # trailing newline, the committed file has one. echo "" echo "--- the synced hooks file ends in a newline ---" if [[ -n "$(tail -c 1 "$FIXTURE/hooks/hooks.json")" ]]; then fail "hooks/hooks.json has no trailing newline — end-of-file-fixer will re-dirty it every sync" else pass "hooks/hooks.json is newline-terminated" fi # --- 3. tests/ fixtures are excluded from the mirror --- echo "" echo "--- tests/ subdirectories are not mirrored ---" if [[ ! -e "$FIXTURE/skills/hello/tests" ]]; then pass "skills/hello/tests/ was not copied into the mirror" else fail "skills/hello/tests/ was copied into the mirror — should be excluded" fi # --- 3b. ...but a deeper tests/ that is a template ASSET must survive --- # The exclusion above is depth-scoped to //tests. Stripping every # directory named tests at any depth also deletes template trees a skill ships for # its own scaffolder to copy from — which is what broke the mirrored # skills/skill-author/scripts/new-skill.sh (`sed: can't read .../tests/README.md`, # half-written scaffold left behind) while the .apm/ original still worked. echo "" echo "--- a tests/ directory nested under assets/templates/ is preserved ---" if [[ -f "$FIXTURE/skills/hello/assets/templates/tests/README.md" ]]; then pass "skills/hello/assets/templates/tests/ survived the sync" else fail "skills/hello/assets/templates/tests/ was stripped — template assets are not dev fixtures" fi # --- 4. --check is clean immediately after a real sync --- echo "" echo "--- --check is clean right after syncing ---" if bash "$SCRIPT" --check "$FIXTURE" > /dev/null 2>&1; then pass "no drift reported immediately after syncing" else fail "drift reported right after syncing — sync and check disagree" fi # --- 5. New .apm/ content is detected as drift, and a re-sync clears it --- echo "" echo "--- new .apm/ content is detected as drift and cleared by re-sync ---" mkdir -p "$FIXTURE/.apm/skills/second" cat > "$FIXTURE/.apm/skills/second/SKILL.md" <<'EOF' --- name: second description: second --- Second. EOF if bash "$SCRIPT" --check "$FIXTURE" > /dev/null 2>&1; then fail "no drift reported after adding a new skill under .apm/ — expected drift" else pass "new .apm/ content is detected as drift" bash "$SCRIPT" "$FIXTURE" > /dev/null 2>&1 if bash "$SCRIPT" --check "$FIXTURE" > /dev/null 2>&1; then pass "re-sync clears the drift" else fail "re-sync did not clear the drift" fi fi # --- 6. A plugin dir with no .apm/ is skipped cleanly, not treated as an error --- echo "" echo "--- a plugin dir with no .apm/ is skipped, not failed ---" NO_APM="$(mktemp -d)"; track "$NO_APM" if bash "$SCRIPT" "$NO_APM" > /dev/null 2>&1 && bash "$SCRIPT" --check "$NO_APM" > /dev/null 2>&1; then pass "a plugin dir with no .apm/ exits 0 in both real and --check mode" else fail "a plugin dir with no .apm/ should exit 0 (skip), not fail" fi # --- 7. A plugin dir that doesn't exist at all is a hard failure, not a skip --- echo "" echo "--- a plugin dir that does not exist fails, distinct from an existing-but-empty one ---" MISSING_ROOT="$(mktemp -d)"; track "$MISSING_ROOT" MISSING="$MISSING_ROOT/does-not-exist" if bash "$SCRIPT" "$MISSING" > /dev/null 2>&1; then fail "exited 0 for a plugin dir that does not exist — expected a hard failure" else pass "a nonexistent plugin dir fails instead of silently skipping" fi # --- 8. --check never mutates the real plugin root, even on first-time manifest creation --- echo "" echo "--- --check does not create .claude-plugin/plugin.json or .github/plugin/plugin.json ---" FIXTURE8="$(make_fixture)"; track "$FIXTURE8" bash "$SCRIPT" --check "$FIXTURE8" > /dev/null 2>&1 || true if [[ ! -e "$FIXTURE8/.claude-plugin/plugin.json" ]] && [[ ! -e "$FIXTURE8/.github/plugin/plugin.json" ]]; then pass "--check leaves the real plugin root without a first-write plugin.json" else fail "--check created plugin.json in the real plugin root — it must never mutate it" fi # --- 9. A duplicate plugin-dir basename among arguments fails fast, not silently --- echo "" echo "--- duplicate plugin dir basenames among arguments are rejected ---" DUP_PARENT_A="$(mktemp -d)"; track "$DUP_PARENT_A" DUP_PARENT_B="$(mktemp -d)"; track "$DUP_PARENT_B" mkdir -p "$DUP_PARENT_A/dup" "$DUP_PARENT_B/dup" if bash "$SCRIPT" "$DUP_PARENT_A/dup" "$DUP_PARENT_B/dup" > /dev/null 2>&1; then fail "exited 0 with two plugin-dir arguments sharing a basename — expected a collision error" else pass "rejects two plugin-dir arguments that share a basename" fi # --- 10. Real sync re-injects mcpServers that apm's Copilot builder strips --- echo "" echo "--- real sync re-injects mcpServers into .github/plugin/plugin.json ---" FIXTURE10="$(make_fixture_with_mcp '{"mcpServers":{"demo":{"command":"demo-server","type":"stdio"}}}')"; track "$FIXTURE10" bash "$SCRIPT" "$FIXTURE10" > /dev/null 2>&1 if jq -e '.mcpServers.demo.command == "demo-server"' "$FIXTURE10/.github/plugin/plugin.json" > /dev/null 2>&1; then pass "mcpServers from .mcp.json is present in .github/plugin/plugin.json after a real sync" else fail "mcpServers was not re-injected into .github/plugin/plugin.json" fi # --- 11. An empty .mcp.json does not add a redundant mcpServers: {} --- echo "" echo "--- an empty .mcp.json does not add mcpServers: {} ---" FIXTURE11="$(make_fixture_with_mcp '{"mcpServers":{}}')"; track "$FIXTURE11" bash "$SCRIPT" "$FIXTURE11" > /dev/null 2>&1 if jq -e 'has("mcpServers") | not' "$FIXTURE11/.github/plugin/plugin.json" > /dev/null 2>&1; then pass "an empty .mcp.json does not add mcpServers to .github/plugin/plugin.json" else fail "an empty .mcp.json still added mcpServers -- should match apm's own omit-when-empty convention" fi # --- 12. --check detects drift in the compiled plugin.json (apm.yml content changed) --- echo "" echo "--- --check detects plugin.json content drift from apm.yml after a version bump ---" FIXTURE12="$(make_fixture)"; track "$FIXTURE12" bash "$SCRIPT" "$FIXTURE12" > /dev/null 2>&1 if bash "$SCRIPT" --check "$FIXTURE12" > /dev/null 2>&1; then pass "check is clean right after the initial sync (baseline for this test)" else fail "check reported drift right after the initial sync -- can't test the version-bump case" fi # Bump the version in apm.yml without re-syncing -- the compiled # .claude-plugin/plugin.json is now stale relative to what apm pack would # currently produce. cat > "$FIXTURE12/apm.yml" <<'YAML' name: fixture version: 0.0.2 description: fixture license: MIT type: hybrid targets: - claude dependencies: apm: [] mcp: [] includes: auto devDependencies: apm: [] scripts: {} YAML if bash "$SCRIPT" --check "$FIXTURE12" > /dev/null 2>&1; then fail "no drift reported after bumping apm.yml's version -- plugin.json should be stale" else pass "plugin.json content drift (version bump) is detected" bash "$SCRIPT" "$FIXTURE12" > /dev/null 2>&1 if bash "$SCRIPT" --check "$FIXTURE12" > /dev/null 2>&1; then pass "re-sync clears the plugin.json drift" else fail "re-sync did not clear the plugin.json drift" fi fi # --- 13. --check detects an orphaned hooks file after .apm/hooks/ is removed --- echo "" echo "--- --check detects an orphaned hooks/hooks.json when .apm/hooks/ is removed ---" FIXTURE13="$(make_fixture)"; track "$FIXTURE13" bash "$SCRIPT" "$FIXTURE13" > /dev/null 2>&1 if [[ ! -f "$FIXTURE13/hooks/hooks.json" ]]; then fail "initial sync did not create hooks/hooks.json -- can't test the orphan case" fi rm -rf "$FIXTURE13/.apm/hooks" if bash "$SCRIPT" --check "$FIXTURE13" > /dev/null 2>&1; then fail "no drift reported for an orphaned hooks/hooks.json after .apm/hooks/ removal" else pass "orphaned hooks/hooks.json is detected as drift" bash "$SCRIPT" "$FIXTURE13" > /dev/null 2>&1 if [[ ! -e "$FIXTURE13/hooks/hooks.json" ]]; then pass "re-sync removes the orphaned hooks/hooks.json" else fail "re-sync left the orphaned hooks/hooks.json in place" fi if bash "$SCRIPT" --check "$FIXTURE13" > /dev/null 2>&1; then pass "re-sync clears the orphaned-hooks drift" else fail "re-sync did not clear the orphaned-hooks drift" fi fi # --- 14. A legacy root-level hooks.json is stale output, not content --- # Every plugin synced by an earlier revision of this script carries one. Nothing # reads it (no `hooks` pointer in the compiled plugin.json, and Claude Code's # convention scan looks at hooks/hooks.json), so --check must flag it and a real # sync must delete it. echo "" echo "--- a legacy root-level hooks.json is reported as drift and removed by a sync ---" FIXTURE14="$(make_fixture)"; track "$FIXTURE14" bash "$SCRIPT" "$FIXTURE14" > /dev/null 2>&1 printf '{"hooks": {"PreToolUse": []}}\n' > "$FIXTURE14/hooks.json" if bash "$SCRIPT" --check "$FIXTURE14" > /dev/null 2>&1; then fail "no drift reported for a leftover root-level hooks.json" else pass "a leftover root-level hooks.json is reported as drift" bash "$SCRIPT" "$FIXTURE14" > /dev/null 2>&1 if [[ ! -e "$FIXTURE14/hooks.json" ]] && [[ -f "$FIXTURE14/hooks/hooks.json" ]]; then pass "re-sync deletes the root-level hooks.json and keeps hooks/hooks.json" else fail "re-sync did not clean up the root-level hooks.json" fi fi # --- 15. Deleting a skill from .apm/ leaves a stale mirror a re-sync must clear --- # Without sync_dir()'s rm -rf of the destination before recopying, --check would # report a drift that no amount of re-syncing could ever clear -- a permanently # unfixable pre-push failure. This is the assertion that pins that wipe. echo "" echo "--- a skill deleted from .apm/ is removed from the mirror by a re-sync ---" FIXTURE15="$(make_fixture)"; track "$FIXTURE15" mkdir -p "$FIXTURE15/.apm/skills/doomed" cat > "$FIXTURE15/.apm/skills/doomed/SKILL.md" <<'EOF' --- name: doomed description: doomed --- Doomed. EOF bash "$SCRIPT" "$FIXTURE15" > /dev/null 2>&1 if [[ ! -f "$FIXTURE15/skills/doomed/SKILL.md" ]]; then fail "initial sync did not mirror skills/doomed -- can't test the stale-skill case" else rm -rf "$FIXTURE15/.apm/skills/doomed" if bash "$SCRIPT" --check "$FIXTURE15" > /dev/null 2>&1; then fail "no drift reported for a mirrored skill deleted from .apm/" else pass "a mirrored skill deleted from .apm/ is reported as drift" bash "$SCRIPT" "$FIXTURE15" > /dev/null 2>&1 if [[ ! -e "$FIXTURE15/skills/doomed" ]]; then pass "re-sync removes the stale skills/doomed/ from the mirror" else fail "re-sync left the stale skills/doomed/ behind — this drift would be unfixable" fi if bash "$SCRIPT" --check "$FIXTURE15" > /dev/null 2>&1; then pass "re-sync clears the stale-skill drift" else fail "re-sync did not clear the stale-skill drift" fi fi fi # --- 16. Drift in each of the less-obvious MIRROR_DIRS is detected --- # agents/ and skills/ are exercised everywhere above; commands/, instructions/, and # extensions/ were previously unreachable by the fixture, so dropping them from # MIRROR_DIRS entirely still passed the suite. echo "" echo "--- drift in commands/, instructions/, and extensions/ is detected ---" for CATEGORY_PATH in commands/mycmd.md instructions/style.instructions.md extensions/thing.md; do FIXTURE16="$(make_fixture)"; track "$FIXTURE16" bash "$SCRIPT" "$FIXTURE16" > /dev/null 2>&1 if [[ ! -f "$FIXTURE16/$CATEGORY_PATH" ]]; then fail "sync did not mirror $CATEGORY_PATH at all — is its category still in MIRROR_DIRS?" continue fi printf 'tampered\n' >> "$FIXTURE16/$CATEGORY_PATH" if bash "$SCRIPT" --check "$FIXTURE16" > /dev/null 2>&1; then fail "no drift reported after tampering with $CATEGORY_PATH" else pass "drift in $CATEGORY_PATH is detected" fi done # --- 17. --check reports every drift in one run, not just the first --- # The DRIFT-detail `diff | sed` pipelines return non-zero under `set -o pipefail`; # without an explicit `|| true` guard, `set -e` aborts the per-plugin subshell after # the first reported drift, turning one push into N fix/re-push cycles. echo "" echo "--- --check reports all independent drifts in a single run ---" FIXTURE17="$(make_fixture)"; track "$FIXTURE17" bash "$SCRIPT" "$FIXTURE17" > /dev/null 2>&1 printf 'tampered\n' >> "$FIXTURE17/agents/foo.agent.md" printf 'tampered\n' >> "$FIXTURE17/skills/hello/SKILL.md" printf 'tampered\n' >> "$FIXTURE17/commands/mycmd.md" printf 'tampered\n' >> "$FIXTURE17/instructions/style.instructions.md" mkdir -p "$FIXTURE17/hooks" printf '{"hooks": {"PreToolUse": [], "tampered": true}}\n' > "$FIXTURE17/hooks/hooks.json" CHECK17="$(bash "$SCRIPT" --check "$FIXTURE17" 2>&1 || true)" MISSED="" for CATEGORY_PATH in agents skills commands instructions hooks/hooks.json; do case "$CHECK17" in *"DRIFT $FIXTURE17/$CATEGORY_PATH"*) ;; *) MISSED="$MISSED $CATEGORY_PATH" ;; esac done if [[ -z "$MISSED" ]]; then pass "all five independent drifts are reported in one --check run" else fail "--check stopped early — never reported drift for:$MISSED" fi # --- 18. --check sees a mode change on a mirrored executable --- # `diff -r` compares content only, so a chmod -x left --check at exit 0 while a real # sync silently restored the bit — check and sync disagreeing. echo "" echo "--- --check detects a mode change on a mirrored executable ---" FIXTURE18="$(make_fixture)"; track "$FIXTURE18" bash "$SCRIPT" "$FIXTURE18" > /dev/null 2>&1 if [[ ! -x "$FIXTURE18/skills/hello/scripts/run.sh" ]]; then fail "sync did not preserve the executable bit on skills/hello/scripts/run.sh" else pass "sync preserves the executable bit on a mirrored script" chmod -x "$FIXTURE18/skills/hello/scripts/run.sh" if bash "$SCRIPT" --check "$FIXTURE18" > /dev/null 2>&1; then fail "no drift reported after chmod -x on a mirrored executable" else pass "a mode change on a mirrored executable is detected as drift" bash "$SCRIPT" "$FIXTURE18" > /dev/null 2>&1 if [[ -x "$FIXTURE18/skills/hello/scripts/run.sh" ]]; then pass "re-sync restores the executable bit" else fail "re-sync did not restore the executable bit" fi fi fi # --- 19. --check sees a mirrored file replaced by a symlink --- # `diff -r` dereferences symlinks, so a symlink to byte-identical content reads as # no drift while a real sync replaces it with a regular file. echo "" echo "--- --check detects a mirrored file swapped for a symlink ---" FIXTURE19="$(make_fixture)"; track "$FIXTURE19" bash "$SCRIPT" "$FIXTURE19" > /dev/null 2>&1 SYMLINK_TARGET="$FIXTURE19/decoy-agent.md" cp "$FIXTURE19/agents/foo.agent.md" "$SYMLINK_TARGET" rm -f "$FIXTURE19/agents/foo.agent.md" ln -s "$SYMLINK_TARGET" "$FIXTURE19/agents/foo.agent.md" if bash "$SCRIPT" --check "$FIXTURE19" > /dev/null 2>&1; then fail "no drift reported after replacing a mirrored file with a symlink to identical content" else pass "a mirrored file replaced by a symlink is detected as drift" bash "$SCRIPT" "$FIXTURE19" > /dev/null 2>&1 if [[ -f "$FIXTURE19/agents/foo.agent.md" ]] && [[ ! -L "$FIXTURE19/agents/foo.agent.md" ]]; then pass "re-sync restores it to a regular file" else fail "re-sync did not restore the symlinked mirror entry to a regular file" fi fi echo "" echo "Results: $PASS passed, $FAIL failed" [[ $FAIL -eq 0 ]]