Files
skillshare/ai_docs/tests/extras_flatten_runbook.md
T
Willie b93518e3da test(e2e): add agents runbook and fix all 33 runbooks to 361/361 pass
Add comprehensive agents_commands_runbook.md covering all agent CLI
commands: list, sync, status, diff, collect, uninstall, trash, update,
backup, and doctor (30 steps).

Fix 18 previously failing runbooks:
- Add workdir: $HOME to mdproof.json to prevent workspace pollution
  from project mode auto-detection
- Fix jq assertions using positional index to use select(.name == ...)
- Fix extras_flatten legacy agents/ dir conflict (rm in cleanup)
- Fix auto_create_target_dir sed insertion and Will/Would wording
- Fix uninstall_sync_orphan config indentation for migrated format
- Fix universal_target_path grep pattern (name vs global_name)
- Fix uninstall_all_glob registry.yaml filter in verify step
- Fix target_naming grep for actual CLI warning output
- Fix registry_yaml_split anchored grep for top-level skills:
- Fix skillignore_source_discovery stdout suppression and jq filter
- Fix ui_base_path: use pre-built binary, PID files, high ports,
  redirect server log to stderr to keep JSON pure
- Fix extras init redirect to suppress ANSI warnings in JSON steps
2026-04-07 18:07:08 +08:00

6.8 KiB

CLI E2E Runbook: Extras Flatten Option

Validates flatten: true for extras targets — syncing subdirectory files directly into the target root instead of preserving directory structure.

Origin: Issue #97 — flatten option for extras sync.

Scope

  • flatten: true syncs files flat (ignoring subdirectory structure)
  • --flatten flag on extras init
  • --flatten / --no-flatten on extras mode
  • Filename collision: first file wins, subsequent skipped with warning
  • Flatten + symlink mode: rejected
  • Flatten prune
  • JSON output includes flatten field and warnings

Environment

Run inside devcontainer.

Steps

1. Flatten sync — files from subdirectories land in target root

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/curriculum
mkdir -p ~/.config/skillshare/extras/agents/software
echo "# Tactician" > ~/.config/skillshare/extras/agents/curriculum/tactician.md
echo "# Planner" > ~/.config/skillshare/extras/agents/curriculum/planner.md
echo "# Implementer" > ~/.config/skillshare/extras/agents/software/implementer.md
echo "# Reviewer" > ~/.config/skillshare/extras/agents/reviewer.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras --json -g

Expected:

  • exit_code: 0
  • jq: [.extras[] | select(.name == "agents")][0].targets[0].synced == 4

2. Verify flat file layout — no subdirectories in target

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/sub1 ~/.config/skillshare/extras/agents/sub2
echo "a" > ~/.config/skillshare/extras/agents/sub1/a.md
echo "b" > ~/.config/skillshare/extras/agents/sub2/b.md
echo "c" > ~/.config/skillshare/extras/agents/root.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras -g >/dev/null
echo "files=$(find ~/.claude/agents/ -maxdepth 1 -name '*.md' | wc -l)"
echo "dirs=$(find ~/.claude/agents/ -mindepth 1 -type d | wc -l)"

Expected:

  • exit_code: 0
  • files=3
  • dirs=0

3. Extras list JSON includes flatten field

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss extras list --json -g

Expected:

  • exit_code: 0
  • jq: .[0].targets[0].flatten == true

4. Flatten collision — first file wins, second skipped with warning

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/team-a
mkdir -p ~/.config/skillshare/extras/agents/team-b
echo "# From team-a" > ~/.config/skillshare/extras/agents/team-a/agent.md
echo "# From team-b" > ~/.config/skillshare/extras/agents/team-b/agent.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras --json -g

Expected:

  • exit_code: 0
  • jq: [.extras[] | select(.name == "agents")][0].targets[0].synced == 1
  • jq: [.extras[] | select(.name == "agents")][0].targets[0].skipped == 1
  • jq: [.extras[] | select(.name == "agents")][0].targets[0].warnings | length == 1

5. Flatten collision warning in human-readable output

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/a ~/.config/skillshare/extras/agents/b
echo "1" > ~/.config/skillshare/extras/agents/a/same.md
echo "2" > ~/.config/skillshare/extras/agents/b/same.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras -g

Expected:

  • exit_code: 0
  • flatten conflict

6. Toggle flatten off via extras mode

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss extras agents --no-flatten -g >/dev/null
ss extras list --json -g

Expected:

  • exit_code: 0
  • jq: .[0].targets[0].flatten == false

7. Toggle flatten on via extras mode

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents -g >/dev/null 2>&1
ss extras agents --flatten -g >/dev/null
ss extras list --json -g

Expected:

  • exit_code: 0
  • jq: .[0].targets[0].flatten == true
ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents
echo "x" > ~/.config/skillshare/extras/agents/x.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss extras agents --mode symlink -g 2>&1 || true

Expected:

  • flatten cannot be used with symlink mode

9. Flatten prune — orphaned flat file removed after source deletion

ss extras remove agents --force -g >/dev/null 2>&1 || true
rm -rf ~/.claude/agents ~/.config/skillshare/extras/agents ~/.config/skillshare/agents 2>/dev/null || true
mkdir -p ~/.config/skillshare/extras/agents/sub
echo "# Keep" > ~/.config/skillshare/extras/agents/sub/keep.md
echo "# Remove" > ~/.config/skillshare/extras/agents/sub/remove.md
mkdir -p ~/.claude/agents
ss extras init agents --target ~/.claude/agents --flatten -g >/dev/null 2>&1
ss sync extras -g >/dev/null
rm ~/.config/skillshare/extras/agents/sub/remove.md
ss sync extras --json -g

Expected:

  • exit_code: 0
  • jq: [.extras[] | select(.name == "agents")][0].targets[0].pruned == 1

Pass Criteria

  • All steps pass
  • Flatten sync produces flat symlinks (no subdirectories in target)
  • Collision detection works with correct warning and skip
  • Flatten toggle via --flatten/--no-flatten works
  • Flatten + symlink mode is rejected
  • Prune works with flattened paths