Files
skillshare/ai_docs/tests/sync_extras_runbook.md
T
Willie 48f1d3767f fix(test): improve extras runbooks with jq assertions, idempotency, and init cleanup
- Replace python3 JSON parsing with native mdproof jq: assertions across
  extras_refactor_json_runbook (7 steps simplified)
- Add cat>> idempotency guards (sed -i cleanup) before YAML appends
- Add ssenv --init default extras cleanup in Step 1 of extras_commands
  and sync_extras runbooks to prevent false failures
- Rename runbook.json → mdproof.json (mdproof only reads mdproof.json)
- Move /tmp cleanup from step_setup to setup (per-runbook, not per-step)
  to avoid breaking cross-step dependencies
- Fix ensure-mdproof.sh to upgrade dev binary to latest release
- Add .mdproof/lessons-learned.md with 5 documented gotchas
- Update cli-e2e-test SKILL.md with assertion types, jq best practices,
  --init extras checklist item, and /mdproof skill collaboration
2026-03-12 16:45:02 +08:00

7.3 KiB

CLI E2E Runbook: Extras Sync (Merge, Copy, Symlink modes)

Validates sync extras syncing file-based resources (rules, commands) across AI tools using merge (per-file symlink), copy, and symlink (entire directory) modes.

Origin: Feature #59 — extras sync for rules, commands, agents beyond skills.

Scope

  • sync extras syncs all configured extras
  • Merge mode: per-file symlinks from target to source
  • Copy mode: per-file copies
  • Symlink mode: entire directory symlink
  • Conflict handling: skip without --force, overwrite with --force
  • Orphan pruning: removes files in target that no longer exist in source
  • sync --all syncs skills + extras together
  • No extras configured: prints helpful hint
  • Source directory missing: prints friendly message, continues

Environment

Run inside devcontainer. If ss alias is unavailable, replace ss with skillshare.

Steps

1. Setup: initialize and create extras source directories

# Clean pre-existing extras and target dirs from ssenv --init
ss extras remove rules --force -g 2>/dev/null || true
rm -rf ~/.claude/rules ~/.continue/rules ~/.claude/commands 2>/dev/null || true
# Create extras source dirs using new layout
mkdir -p ~/.config/skillshare/extras/rules
mkdir -p ~/.config/skillshare/extras/commands
echo "# Always use TDD" > ~/.config/skillshare/extras/rules/tdd.md
echo "# Error handling" > ~/.config/skillshare/extras/rules/errors.md
echo "# Deploy command" > ~/.config/skillshare/extras/commands/deploy.md

Expected:

  • exit_code: 0

2. Configure extras in config.yaml

sed -i '/^extras:/,$d' ~/.config/skillshare/config.yaml
cat >> ~/.config/skillshare/config.yaml << 'CONF'

extras:
  - name: rules
    targets:
      - path: ~/.claude/rules
      - path: ~/.continue/rules
        mode: copy
  - name: commands
    targets:
      - path: ~/.claude/commands
        mode: symlink
CONF

Expected:

  • exit_code: 0

3. Dry run: verify sync extras --dry-run shows plan without changes

ss sync extras --dry-run

Expected:

  • exit_code: 0
  • regex: dry.run|Dry run
  • Sync Extras
ls ~/.claude/rules/ 2>/dev/null && echo "dir_exists=yes" || echo "dir_exists=no"

Expected:

  • exit_code: 0
  • dir_exists=no
ss sync extras

Expected:

  • exit_code: 0
  • Sync Extras
  • synced

Verify merge mode (per-file symlinks):

ls -la ~/.claude/rules/
readlink ~/.claude/rules/tdd.md

Expected:

  • exit_code: 0
  • tdd.md
  • errors.md
  • regex: skillshare/extras/rules/tdd.md

5. Verify copy mode (real file copies)

ls -la ~/.continue/rules/
# Verify it's a real file (not symlink)
test -f ~/.continue/rules/tdd.md && ! test -L ~/.continue/rules/tdd.md && echo "real_file=yes" || echo "real_file=no"
cat ~/.continue/rules/tdd.md

Expected:

  • exit_code: 0
  • tdd.md
  • errors.md
  • real_file=yes
  • Always use TDD
ls -la ~/.claude/ | grep commands
readlink ~/.claude/commands
cat ~/.claude/commands/deploy.md

Expected:

  • exit_code: 0
  • commands
  • regex: skillshare/extras/commands
  • Deploy command

7. Idempotent re-sync: running again produces no errors

ss sync extras

Expected:

  • exit_code: 0
  • Sync Extras
  • synced

8. Add new source file and re-sync

echo "# Code review rules" > ~/.config/skillshare/extras/rules/review.md
ss sync extras

Expected:

  • exit_code: 0
ls ~/.claude/rules/ | wc -l | tr -d ' '
ls ~/.continue/rules/ | wc -l | tr -d ' '

Expected:

  • exit_code: 0
  • 3

9. Prune orphans: remove source file and re-sync

rm ~/.config/skillshare/extras/rules/errors.md
ss sync extras

Expected:

  • exit_code: 0
  • pruned
ls ~/.claude/rules/
ls ~/.continue/rules/

Expected:

  • exit_code: 0
  • tdd.md
  • review.md
  • Not errors.md

10. Conflict handling: existing file without --force

Create a conflict — a real file at a target path where merge would create a symlink:

# Remove the symlink first
rm ~/.claude/rules/tdd.md
# Create a real file (user-created content)
echo "my local notes" > ~/.claude/rules/tdd.md
ss sync extras

Expected:

  • exit_code: 0
cat ~/.claude/rules/tdd.md

Expected:

  • exit_code: 0

11. Conflict handling: --force overwrites

ss sync extras --force

Expected:

  • exit_code: 0
readlink ~/.claude/rules/tdd.md
cat ~/.claude/rules/tdd.md

Expected:

  • exit_code: 0
  • regex: skillshare/extras/rules/tdd.md
  • Always use TDD

12. sync --all: syncs both skills and extras

ss sync --all

Expected:

  • exit_code: 0
  • Sync Extras
  • synced

13. No extras configured: helpful hint

# Back up config, remove extras section
cp ~/.config/skillshare/config.yaml ~/.config/skillshare/config.yaml.bak
sed -i '/^extras:/,$d' ~/.config/skillshare/config.yaml
ss sync extras

Expected:

  • exit_code: 0
  • regex: No extras configured
# Restore config
cp ~/.config/skillshare/config.yaml.bak ~/.config/skillshare/config.yaml

Expected:

  • exit_code: 0

14. Source directory missing: friendly message

# Add an extra with non-existent source (idempotent: remove if exists, then init)
ss extras remove nonexistent --force -g 2>/dev/null || true
ss extras init nonexistent --target ~/.claude/nonexistent -g
rm -rf ~/.config/skillshare/extras/nonexistent
ss sync extras

Expected:

  • exit_code: 0
  • regex: not exist|not found|missing
  • Sync Extras

15. Auto-migration: legacy flat path to extras//

# Remove the nonexistent extra from step 14 first
ss extras remove nonexistent --force -g 2>/dev/null || true
# Add a new extra via ss extras init
ss extras init migrate-test --target ~/.claude/migrate-rules -g
# Remove the new-style directory that init created
rm -rf ~/.config/skillshare/extras/migrate-test
# Create files at legacy (flat) path to simulate old layout
mkdir -p ~/.config/skillshare/migrate-test
echo "# Legacy rule" > ~/.config/skillshare/migrate-test/legacy.md
test -d ~/.config/skillshare/migrate-test && echo "legacy_exists=yes"
test -d ~/.config/skillshare/extras/migrate-test && echo "new_exists=yes" || echo "new_exists=no"

Expected:

  • exit_code: 0
  • legacy_exists=yes
  • new_exists=no
ss sync extras 2>&1

Expected:

  • exit_code: 0
  • regex: Migrated|migrated
  • Sync Extras
test -d ~/.config/skillshare/extras/migrate-test && echo "migrated=yes" || echo "migrated=no"
test -d ~/.config/skillshare/migrate-test && echo "legacy_still=yes" || echo "legacy_still=no"

Expected:

  • exit_code: 0
  • migrated=yes
  • legacy_still=no

16. Nested directory structure preserved

mkdir -p ~/.config/skillshare/extras/rules/lang/go
echo "# Go style" > ~/.config/skillshare/extras/rules/lang/go/style.md
ss sync extras

Expected:

  • exit_code: 0
cat ~/.claude/rules/lang/go/style.md
readlink ~/.claude/rules/lang/go/style.md

Expected:

  • exit_code: 0
  • Go style
  • regex: skillshare/extras/rules/lang/go/style.md

Pass Criteria

All 16 steps pass. Key behaviors validated:

  • Three sync modes (merge, copy, symlink) work correctly
  • Conflict detection and --force override
  • Orphan pruning removes stale files
  • Idempotent re-sync
  • sync --all combines skills + extras
  • Auto-migration from legacy flat path to extras//
  • Nested directories preserved
  • Graceful handling of missing source/config