mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
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
6.6 KiB
6.6 KiB
CLI E2E Runbook: UI Base Path for Reverse Proxy
Verifies skillshare ui --base-path serves the dashboard and API under a sub-path prefix, as required for reverse proxy deployments (issue #85).
Scope
--base-pathflag routes API and SPA under a prefix- Bare path redirect (
/skillshare→/skillshare/) - Unprefixed paths return 404
__BASE_PATH__injected intoindex.html- SPA fallback works under base path
-bshort flag acceptedSKILLSHARE_UI_BASE_PATHenv var fallback- Multi-level base path (
/tools/skillshare) - No base path = unchanged behavior (regression)
Environment
Run inside devcontainer. Uses /tmp/ for isolated HOME and a fake UI dist.
Server uses port 49821 to avoid conflicts with existing UI on 19420.
Step 0: Setup isolated HOME and fake UI dist
# Kill any leftover UI servers from previous test runs
kill $(cat /tmp/basepath-server.pid /tmp/basepath-server2.pid 2>/dev/null) 2>/dev/null || true
rm -f /tmp/basepath-server.pid /tmp/basepath-server2.pid
sleep 1
export E2E_HOME="/tmp/ss-e2e-basepath"
rm -rf "$E2E_HOME"
mkdir -p "$E2E_HOME/.config/skillshare/skills/demo"
mkdir -p "$E2E_HOME/.cache/skillshare/ui/dev"
mkdir -p "$E2E_HOME/.claude/skills"
cat > "$E2E_HOME/.config/skillshare/skills/demo/SKILL.md" <<'SKILL'
---
name: demo
---
# Demo skill
SKILL
cat > "$E2E_HOME/.config/skillshare/config.yaml" <<'YAML'
source: ~/.config/skillshare/skills
mode: merge
targets:
claude:
path: ~/.claude/skills
YAML
cat > "$E2E_HOME/.cache/skillshare/ui/dev/index.html" <<'HTML'
<!DOCTYPE html>
<html>
<head><title>Skillshare UI</title></head>
<body><h1>Dashboard</h1></body>
</html>
HTML
echo "setup_ok=yes"
Expected:
- exit_code: 0
- setup_ok=yes
Step 1: Start server with --base-path
export E2E_HOME="/tmp/ss-e2e-basepath"
export HOME="$E2E_HOME"
export XDG_CONFIG_HOME="$E2E_HOME/.config"
export XDG_DATA_HOME="$E2E_HOME/.local/share"
export XDG_STATE_HOME="$E2E_HOME/.local/state"
export XDG_CACHE_HOME="$E2E_HOME/.cache"
kill $(cat /tmp/basepath-server.pid 2>/dev/null) 2>/dev/null || true
rm -f /tmp/basepath-server.pid
sleep 1
/workspace/bin/skillshare ui --base-path /skillshare --host 0.0.0.0 --port 49821 --no-open -g > /tmp/basepath-server.log 2>&1 &
SERVER_PID=$!
echo $SERVER_PID > /tmp/basepath-server.pid
echo "server_pid=$SERVER_PID"
sleep 5
cat /tmp/basepath-server.log
Expected:
- exit_code: 0
- regex: server_pid=\d+
- regex: running at http://.*:49821/skillshare/
Step 2: API health with prefix returns 200
curl -sf http://localhost:49821/skillshare/api/health
Expected:
- exit_code: 0
- jq: .status == "ok"
Step 3: API health without prefix returns 404
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:49821/api/health)
echo "status=$HTTP_CODE"
test "$HTTP_CODE" = "404" && echo "correctly_rejected=yes"
Expected:
- exit_code: 0
- status=404
- correctly_rejected=yes
Step 4: Bare path redirects to trailing slash
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:49821/skillshare)
LOCATION=$(curl -s -o /dev/null -w "%{redirect_url}" http://localhost:49821/skillshare)
echo "status=$HTTP_CODE"
echo "location=$LOCATION"
Expected:
- exit_code: 0
- status=301
- regex: location=.*/skillshare/
Step 5: Root path returns 404
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:49821/)
echo "status=$HTTP_CODE"
test "$HTTP_CODE" = "404" && echo "root_blocked=yes"
Expected:
- exit_code: 0
- status=404
- root_blocked=yes
Step 6: Index.html served with BASE_PATH injection
BODY=$(curl -sf http://localhost:49821/skillshare/)
echo "$BODY"
echo "$BODY" | grep -q '__BASE_PATH__' && echo "injection_found=yes"
echo "$BODY" | grep -q '"/skillshare"' && echo "value_correct=yes"
Expected:
- exit_code: 0
- injection_found=yes
- value_correct=yes
- BASE_PATH
Step 7: SPA fallback serves index.html for unknown routes
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:49821/skillshare/skills/nonexistent)
BODY=$(curl -sf http://localhost:49821/skillshare/skills/nonexistent)
echo "status=$HTTP_CODE"
echo "$BODY" | grep -q '__BASE_PATH__' && echo "spa_fallback_ok=yes"
Expected:
- exit_code: 0
- status=200
- spa_fallback_ok=yes
Step 8: API overview returns valid data
curl -sf http://localhost:49821/skillshare/api/overview
Expected:
- exit_code: 0
- jq: .skillCount >= 0
- jq: .mode == "merge"
Step 9: Stop server and cleanup
kill $(cat /tmp/basepath-server.pid 2>/dev/null) 2>/dev/null || true
rm -f /tmp/basepath-server.pid
sleep 1
echo "server_stopped=yes"
Expected:
- exit_code: 0
- server_stopped=yes
Step 10: --base-path missing value returns error
/workspace/bin/skillshare ui --base-path 2>&1 || true
Expected:
- --base-path requires a value
Step 11: -b short flag missing value returns error
/workspace/bin/skillshare ui -b 2>&1 || true
Expected:
- --base-path requires a value
Step 12: Env var SKILLSHARE_UI_BASE_PATH is read
export E2E_HOME="/tmp/ss-e2e-basepath"
export HOME="$E2E_HOME"
export XDG_CONFIG_HOME="$E2E_HOME/.config"
export XDG_DATA_HOME="$E2E_HOME/.local/share"
export XDG_STATE_HOME="$E2E_HOME/.local/state"
export XDG_CACHE_HOME="$E2E_HOME/.cache"
export SKILLSHARE_UI_BASE_PATH="/from-env"
kill $(cat /tmp/basepath-server.pid /tmp/basepath-server2.pid 2>/dev/null) 2>/dev/null || true
rm -f /tmp/basepath-server.pid /tmp/basepath-server2.pid
sleep 1
/workspace/bin/skillshare ui --host 0.0.0.0 --port 49822 --no-open -g > /tmp/basepath-env.log 2>&1 &
echo $! > /tmp/basepath-server2.pid
sleep 3
cat /tmp/basepath-env.log >&2
curl -sf http://localhost:49822/from-env/api/health
kill $(cat /tmp/basepath-server2.pid 2>/dev/null) 2>/dev/null || true
Expected:
- exit_code: 0
- jq: .status == "ok"
Step 13: Final cleanup
kill $(cat /tmp/basepath-server.pid /tmp/basepath-server2.pid 2>/dev/null) 2>/dev/null || true
sleep 1
rm -f /tmp/basepath-server.pid /tmp/basepath-server2.pid
rm -rf /tmp/ss-e2e-basepath /tmp/basepath-server.log /tmp/basepath-env.log
echo "cleanup_done=yes"
Expected:
- exit_code: 0
- cleanup_done=yes
Pass/Fail Criteria
Pass when all are true:
- API endpoints accessible under
/skillshare/api/... - API endpoints return 404 without prefix
- Bare path redirects to trailing slash
- Root path returns 404
index.htmlcontains injected__BASE_PATH__- SPA fallback serves
index.htmlfor unknown routes --base-path/-bflag validation worksSKILLSHARE_UI_BASE_PATHenv var is respected
Fail if any step errors or API is unreachable under the base path.