diff --git a/.devcontainer/bin/docs b/.devcontainer/bin/docs index 8997fec1d..20d30c070 100755 --- a/.devcontainer/bin/docs +++ b/.devcontainer/bin/docs @@ -1,9 +1,71 @@ -#!/bin/sh -# Devcontainer: ensure Docusaurus dev server is running, then print URL. -URL="http://localhost:3000" +#!/usr/bin/env bash +# Devcontainer: start/stop Docusaurus. +# Usage: docs # start → http://localhost:3000 +# docs stop # stop +set -euo pipefail -if ! curl -sf "$URL" >/dev/null 2>&1; then - dev-servers start docusaurus - sleep 2 +PORT=3000 +PIDDIR=/tmp/dev-servers +LOGDIR=/tmp +mkdir -p "$PIDDIR" + +# Resolve pnpm +PNPM_BIN="" +if command -v pnpm >/dev/null 2>&1; then + PNPM_BIN="$(command -v pnpm)" +elif [ -x /usr/local/share/pnpm/pnpm ]; then + PNPM_BIN="/usr/local/share/pnpm/pnpm" +elif [ -x /usr/local/bin/pnpm ]; then + PNPM_BIN="/usr/local/bin/pnpm" +elif [ -x /usr/local/share/nvm/current/bin/pnpm ]; then + PNPM_BIN="/usr/local/share/nvm/current/bin/pnpm" fi -echo "✓ Docs: $URL" + +is_port_open() { + timeout 1 bash -c "echo > /dev/tcp/127.0.0.1/$1" 2>/dev/null +} + +kill_pid_file() { + local pf="$1" + [ -f "$pf" ] || return 0 + local pid; pid=$(cat "$pf") + pkill -P "$pid" 2>/dev/null || true + kill "$pid" 2>/dev/null || true + sleep 0.3 + kill -9 "$pid" 2>/dev/null || true + rm -f "$pf" +} + +case "${1:-start}" in + stop) + kill_pid_file "$PIDDIR/docusaurus.pid" + fuser -k $PORT/tcp 2>/dev/null || true + echo " docusaurus stopped" + ;; + *) + if is_port_open $PORT; then + echo "✓ Docs: http://localhost:$PORT (run 'docs stop' to shut down)" + exit 0 + fi + if [ -z "$PNPM_BIN" ]; then + echo " docusaurus failed: pnpm not found" >&2 + exit 1 + fi + if [ ! -x /workspace/website/node_modules/.bin/docusaurus ]; then + (cd /workspace/website && "$PNPM_BIN" install --frozen-lockfile > "$LOGDIR/docusaurus-deps.log" 2>&1) || true + fi + (cd /workspace/website && nohup "$PNPM_BIN" exec docusaurus start --host 0.0.0.0 --port $PORT --no-open > "$LOGDIR/docusaurus-dev.log" 2>&1 & + echo $! > "$PIDDIR/docusaurus.pid") + for _ in $(seq 1 60); do + is_port_open $PORT && break + sleep 1 + done + if is_port_open $PORT; then + echo "✓ Docs: http://localhost:$PORT (run 'docs stop' to shut down)" + else + echo " docusaurus failed to start (see $LOGDIR/docusaurus-dev.log)" >&2 + tail -n 10 "$LOGDIR/docusaurus-dev.log" 2>/dev/null | sed 's/^/ /' >&2 + exit 1 + fi + ;; +esac diff --git a/.devcontainer/bin/ui b/.devcontainer/bin/ui index bcd90ad44..7f8e79b0c 100755 --- a/.devcontainer/bin/ui +++ b/.devcontainer/bin/ui @@ -1,17 +1,114 @@ -#!/bin/sh -# Devcontainer: switch to global-mode API and open dashboard. -URL="http://localhost:19420" +#!/usr/bin/env bash +# Devcontainer: launch dashboard (API backend + Vite frontend). +# Usage: ui # global mode → http://localhost:5173 +# ui -p # project mode (~/demo-project) → http://localhost:5173 +# ui stop # stop API + Vite +set -euo pipefail -# Already running in global mode via dev-servers? Just print URL. -if [ -f /tmp/dev-servers/api.pid ] && kill -0 "$(cat /tmp/dev-servers/api.pid)" 2>/dev/null; then - echo "✓ Dashboard (global): $URL" +PORT=19420 +VITE_PORT=5173 +PIDDIR=/tmp/dev-servers +LOGDIR=/tmp +mkdir -p "$PIDDIR" + +# Resolve pnpm +PNPM_BIN="" +if command -v pnpm >/dev/null 2>&1; then + PNPM_BIN="$(command -v pnpm)" +elif [ -x /usr/local/share/pnpm/pnpm ]; then + PNPM_BIN="/usr/local/share/pnpm/pnpm" +elif [ -x /usr/local/bin/pnpm ]; then + PNPM_BIN="/usr/local/bin/pnpm" +elif [ -x /usr/local/share/nvm/current/bin/pnpm ]; then + PNPM_BIN="/usr/local/share/nvm/current/bin/pnpm" +fi + +is_port_open() { + timeout 1 bash -c "echo > /dev/tcp/127.0.0.1/$1" 2>/dev/null +} + +kill_pid_file() { + local pf="$1" + [ -f "$pf" ] || return 0 + local pid; pid=$(cat "$pf") + pkill -P "$pid" 2>/dev/null || true + kill "$pid" 2>/dev/null || true + sleep 0.3 + kill -9 "$pid" 2>/dev/null || true + rm -f "$pf" +} + +# Parse args +MODE="global" +ACTION="start" +for arg in "$@"; do + case "$arg" in + -p|--project) MODE="project" ;; + -g|--global) MODE="global" ;; + stop) ACTION="stop" ;; + esac +done + +# ── stop ── +if [ "$ACTION" = "stop" ]; then + kill_pid_file "$PIDDIR/api.pid" + pkill -f 'skillshare.* ui' 2>/dev/null || true + fuser -k $PORT/tcp 2>/dev/null || true + kill_pid_file "$PIDDIR/vite.pid" + fuser -k $VITE_PORT/tcp 2>/dev/null || true + echo " api + vite stopped" exit 0 fi -# Kill project-mode server if running. -pkill -f 'skillshare ui -p --host' 2>/dev/null || true -sleep 0.5 +# ── start ── -# Start global mode via dev-servers (background). -dev-servers start api -echo "✓ Dashboard (global): $URL" +# Stop old API. +kill_pid_file "$PIDDIR/api.pid" +pkill -f 'skillshare.* ui' 2>/dev/null || true +fuser -k $PORT/tcp 2>/dev/null || true +for _ in 1 2 3 4 5 6; do + is_port_open $PORT || break + sleep 0.5 +done + +# Build binary. +printf " %-12s building..." "api" +if ! (cd /workspace && /usr/local/go/bin/go build -o /tmp/skillshare-dev ./cmd/skillshare) 2>"$LOGDIR/ui-build.log"; then + echo " failed (see $LOGDIR/ui-build.log)" + exit 1 +fi +echo " ok" + +# Start API. +if [ "$MODE" = "project" ]; then + cd ~/demo-project +fi +nohup /tmp/skillshare-dev ui "-${MODE:0:1}" --no-open --host 0.0.0.0 --port $PORT > "$LOGDIR/api-dev.log" 2>&1 & +echo $! > "$PIDDIR/api.pid" +printf " %-12s started (%s mode)\n" "api" "$MODE" + +# Ensure Vite is running. +if is_port_open $VITE_PORT; then + printf " %-12s already running (port %s)\n" "vite" "$VITE_PORT" +else + if [ -z "$PNPM_BIN" ]; then + echo " vite skipped: pnpm not found" >&2 + else + if [ ! -x /workspace/ui/node_modules/.bin/vite ]; then + (cd /workspace/ui && "$PNPM_BIN" install --frozen-lockfile > "$LOGDIR/vite-deps.log" 2>&1) || true + fi + (cd /workspace/ui && nohup "$PNPM_BIN" exec vite --host 0.0.0.0 --port $VITE_PORT --strictPort > "$LOGDIR/vite-dev.log" 2>&1 & + echo $! > "$PIDDIR/vite.pid") + for _ in $(seq 1 20); do + is_port_open $VITE_PORT && break + sleep 0.5 + done + if is_port_open $VITE_PORT; then + printf " %-12s started (port %s)\n" "vite" "$VITE_PORT" + else + printf " %-12s failed to start (see %s/vite-dev.log)\n" "vite" "$LOGDIR" >&2 + fi + fi +fi + +echo "✓ Dashboard ($MODE): http://localhost:$VITE_PORT" diff --git a/.devcontainer/bin/ui-p b/.devcontainer/bin/ui-p deleted file mode 100755 index 047013b5d..000000000 --- a/.devcontainer/bin/ui-p +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/sh -# Devcontainer: switch to project-mode API and open dashboard. -URL="http://localhost:19420" - -# Stop global-mode API. -dev-servers stop api 2>/dev/null || true -# Stop any existing project-mode server. -pkill -f 'skillshare ui -p --host' 2>/dev/null || true -sleep 0.5 - -echo "▸ Starting project-mode API (Ctrl-C to stop)" -echo " Dashboard: $URL" - -cd ~/demo-project && exec go run /workspace/cmd/skillshare ui -p --host 0.0.0.0 "$@" diff --git a/.devcontainer/dev-servers.sh b/.devcontainer/dev-servers.sh index 6b5f798d6..9e24b96c3 100755 --- a/.devcontainer/dev-servers.sh +++ b/.devcontainer/dev-servers.sh @@ -12,18 +12,95 @@ if [ "${BASH_VERSINFO[0]}" -lt 4 ]; then exit 1 fi +PNPM_BIN="" +if command -v pnpm >/dev/null 2>&1; then + PNPM_BIN="$(command -v pnpm)" +elif [ -x /usr/local/share/pnpm/pnpm ]; then + PNPM_BIN="/usr/local/share/pnpm/pnpm" +elif [ -x /usr/local/bin/pnpm ]; then + PNPM_BIN="/usr/local/bin/pnpm" +elif [ -x /usr/local/share/nvm/current/bin/pnpm ]; then + PNPM_BIN="/usr/local/share/nvm/current/bin/pnpm" +fi + declare -A PORTS=([api]=19420 [vite]=5173 [docusaurus]=3000) declare -A DIRS=([api]=/workspace [vite]=/workspace/ui [docusaurus]=/workspace/website) declare -A CMDS=( - [api]="go run ./cmd/skillshare ui --no-open --host 0.0.0.0" - [vite]="pnpm run dev" - [docusaurus]="pnpm start --host 0.0.0.0" + [api]="/usr/local/go/bin/go run ./cmd/skillshare ui --no-open --host 0.0.0.0 --port 19420" + [vite]="${PNPM_BIN:-pnpm} exec vite --host 0.0.0.0 --port 5173 --strictPort" + [docusaurus]="${PNPM_BIN:-pnpm} exec docusaurus start --host 0.0.0.0 --port 3000 --no-open" ) -ALL=(api vite docusaurus) +declare -A VERIFY=([api]="skillshare" [vite]="vite" [docusaurus]="docusaurus") +ALL=(vite docusaurus) is_running() { - local pf="$PIDDIR/$1.pid" - [ -f "$pf" ] && kill -0 "$(cat "$pf")" 2>/dev/null + local n="$1" pf="$PIDDIR/$1.pid" + [ -f "$pf" ] || return 1 + local pid + pid=$(cat "$pf") + kill -0 "$pid" 2>/dev/null || { rm -f "$pf"; return 1; } + # Guard against PID reuse: verify cmdline contains expected keyword + if [ -r "/proc/$pid/cmdline" ]; then + tr '\0' ' ' < "/proc/$pid/cmdline" | grep -qi "${VERIFY[$n]}" || { rm -f "$pf"; return 1; } + fi +} + +is_port_open() { + local port="$1" + timeout 1 bash -c "echo > /dev/tcp/127.0.0.1/$port" >/dev/null 2>&1 +} + +wait_for_port() { + local port="$1" + # Wait up to ~60s (webpack/docusaurus first boot can be slow). + for _ in $(seq 1 120); do + if is_port_open "$port"; then + return 0 + fi + sleep 0.5 + done + return 1 +} + +ensure_api_initialized() { + local cfg="$HOME/.config/skillshare/config.yaml" + if [ -f "$cfg" ]; then + return 0 + fi + ( + cd /workspace + /usr/local/go/bin/go run ./cmd/skillshare init -g --no-copy --all-targets --no-git --skill >/tmp/api-init.log 2>&1 + ) +} + +ensure_frontend_deps() { + local n="$1" + local dir="${DIRS[$n]}" + local bin="" + local dep_log="$LOGDIR/${n}-deps.log" + case "$n" in + vite) bin="$dir/node_modules/.bin/vite" ;; + docusaurus) bin="$dir/node_modules/.bin/docusaurus" ;; + *) return 0 ;; + esac + + if [ -x "$bin" ]; then + return 0 + fi + + ( + cd "$dir" + "$PNPM_BIN" install --frozen-lockfile >"$dep_log" 2>&1 + ) +} + +print_failure_tail() { + local n="$1" + local log="$LOGDIR/${n}-dev.log" + if [ -f "$log" ]; then + echo " Last log lines ($log):" >&2 + tail -n 20 "$log" | sed 's/^/ /' >&2 + fi } validate_target() { @@ -36,18 +113,51 @@ validate_target() { do_start() { local n=$1 - if is_running "$n"; then - printf " %-12s already running (port %s)\n" "$n" "${PORTS[$n]}" - return + if { [ "$n" = "vite" ] || [ "$n" = "docusaurus" ]; } && [ -z "$PNPM_BIN" ]; then + printf " %-12s failed: pnpm not found in PATH\n" "$n" >&2 + return 1 + fi + if [ "$n" = "api" ] && ! ensure_api_initialized; then + printf " %-12s bootstrap failed (see /tmp/api-init.log)\n" "$n" >&2 + if [ -f /tmp/api-init.log ]; then + tail -n 20 /tmp/api-init.log | sed 's/^/ /' >&2 + fi + return 1 + fi + if { [ "$n" = "vite" ] || [ "$n" = "docusaurus" ]; } && ! ensure_frontend_deps "$n"; then + printf " %-12s dependency bootstrap failed (see %s/%s-deps.log)\n" "$n" "$LOGDIR" "$n" >&2 + if [ -f "$LOGDIR/${n}-deps.log" ]; then + tail -n 20 "$LOGDIR/${n}-deps.log" | sed 's/^/ /' >&2 + fi + return 1 + fi + if ! is_running "$n" && is_port_open "${PORTS[$n]}"; then + printf " %-12s port %s already in use (unmanaged process)\n" "$n" "${PORTS[$n]}" + return 0 fi - ( cd "${DIRS[$n]}" && nohup ${CMDS[$n]} > "$LOGDIR/${n}-dev.log" 2>&1 & echo $! > "$PIDDIR/${n}.pid" ) - sleep 0.3 if is_running "$n"; then + if is_port_open "${PORTS[$n]}"; then + printf " %-12s already running (port %s)\n" "$n" "${PORTS[$n]}" + return + fi + printf " %-12s running (PID %s) but port %s is not reachable; restarting\n" "$n" "$(cat "$PIDDIR/${n}.pid")" "${PORTS[$n]}" + do_stop "$n" + fi + ( + cd "${DIRS[$n]}" + nohup bash -lc "${CMDS[$n]}" > "$LOGDIR/${n}-dev.log" 2>&1 & + echo $! > "$PIDDIR/${n}.pid" + ) + if is_running "$n" && wait_for_port "${PORTS[$n]}"; then printf " %-12s started → http://localhost:%s\n" "$n" "${PORTS[$n]}" return fi + if is_running "$n"; then + kill "$(cat "$PIDDIR/${n}.pid")" 2>/dev/null || true + fi rm -f "$PIDDIR/${n}.pid" printf " %-12s failed to start (see %s/%s-dev.log)\n" "$n" "$LOGDIR" "$n" >&2 + print_failure_tail "$n" return 1 } @@ -59,12 +169,17 @@ do_stop() { return fi local pid; pid=$(cat "$pf") + # Kill children first (go run → compiled binary), then wrapper bash. + pkill -P "$pid" 2>/dev/null || true kill "$pid" 2>/dev/null || true for _ in 1 2 3 4 5; do kill -0 "$pid" 2>/dev/null || break sleep 0.2 done + pkill -9 -P "$pid" 2>/dev/null || true kill -9 "$pid" 2>/dev/null || true + # Last resort: free the port directly. + fuser -k "${PORTS[$n]}/tcp" 2>/dev/null || true rm -f "$pf" printf " %-12s stopped\n" "$n" } @@ -72,7 +187,13 @@ do_stop() { do_status() { local n=$1 if is_running "$n"; then - printf " %-12s ✓ running port %-5s PID %s\n" "$n" "${PORTS[$n]}" "$(cat "$PIDDIR/$n.pid")" + if is_port_open "${PORTS[$n]}"; then + printf " %-12s ✓ running port %-5s PID %s\n" "$n" "${PORTS[$n]}" "$(cat "$PIDDIR/$n.pid")" + else + printf " %-12s ! running port %-5s unreachable PID %s\n" "$n" "${PORTS[$n]}" "$(cat "$PIDDIR/$n.pid")" + fi + elif is_port_open "${PORTS[$n]}"; then + printf " %-12s ~ listening port %-5s (unmanaged)\n" "$n" "${PORTS[$n]}" else printf " %-12s ✗ stopped\n" "$n" rm -f "$PIDDIR/$n.pid" @@ -88,13 +209,31 @@ targets() { fi } +start_targets() { + local failed=0 + local t="$1" + for n in $(targets "$t"); do + if ! do_start "$n"; then + failed=1 + fi + done + return $failed +} + +stop_targets() { + local t="$1" + for n in $(targets "$t"); do + do_stop "$n" + done +} + case "${1:-help}" in - start) for n in $(targets "${2:-}"); do do_start "$n"; done ;; - stop) for n in $(targets "${2:-}"); do do_stop "$n"; done ;; + start) start_targets "${2:-}" ;; + stop) stop_targets "${2:-}" ;; restart) - for n in $(targets "${2:-}"); do do_stop "$n"; done + stop_targets "${2:-}" sleep 1 - for n in $(targets "${2:-}"); do do_start "$n"; done + start_targets "${2:-}" ;; status) for n in $(targets "${2:-}"); do do_status "$n"; done ;; logs) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 69736ec80..1c400d2dd 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -9,11 +9,11 @@ "pnpmVersion": "10.28.0" } }, - "forwardPorts": [19420, 5173, 3000], + "forwardPorts": [5173, 19420, 3000], "portsAttributes": { - "19420": { "label": "API Server" }, - "5173": { "label": "Vite (UI)" }, - "3000": { "label": "Docusaurus" } + "5173": { "label": "Dashboard (ui)" }, + "19420": { "label": "API Backend" }, + "3000": { "label": "Docs (docs)" } }, "remoteEnv": { "PATH": "/workspace/.devcontainer/bin:/workspace/bin:${containerEnv:PATH}", diff --git a/.devcontainer/setup.sh b/.devcontainer/setup.sh index 0f00b071f..aeeea539c 100755 --- a/.devcontainer/setup.sh +++ b/.devcontainer/setup.sh @@ -27,12 +27,18 @@ echo "▸ Installing website dependencies …" # survives make clean). Only ephemeral symlinks are created here. echo "▸ Installing shortcut commands …" ln -sf /workspace/bin/skillshare /workspace/bin/ss -ln -sf /workspace/.devcontainer/dev-servers.sh /workspace/.devcontainer/bin/dev-servers # ── 3. Global mode init ──────────────────────────────────────────── echo "▸ Initializing global mode …" mkdir -p "$HOME/.claude/skills" -skillshare init -g --no-copy --all-targets --no-git --skill +GLOBAL_CFG="$HOME/.config/skillshare/config.yaml" +if [ -f "$GLOBAL_CFG" ]; then + echo " ✓ Already initialized ($GLOBAL_CFG), skipping init" +elif skillshare status >/dev/null 2>&1; then + echo " ✓ Already initialized (detected via 'skillshare status'), skipping init" +else + skillshare init -g --no-copy --all-targets --no-git --skill +fi # ── 4. Create demo content (shared with sandbox playground) ─────── echo "▸ Creating demo content …" @@ -50,14 +56,11 @@ echo "" echo "Quick start:" echo " ss status # check current state" echo " ss list # see all skills" -echo " ui # global-mode dashboard (auto-started)" -echo " ui-p # switch to project-mode dashboard" -echo " docs # open documentation site" -echo "" -echo "Dev servers (auto-started on container open):" -echo " dev-servers status # check which servers are running" -echo " dev-servers restart # restart all dev servers" -echo " dev-servers logs vite # tail Vite log (api|vite|docusaurus)" +echo " ui # global-mode dashboard → :5173" +echo " ui -p # project-mode dashboard → :5173" +echo " ui stop # stop dashboard" +echo " docs # documentation site → :3000" +echo " docs stop # stop docs" echo "" echo "Audit playground:" echo " ss audit # scan all skills, see findings" diff --git a/.devcontainer/start-dev.sh b/.devcontainer/start-dev.sh index eeb06ae7a..738f024a9 100755 --- a/.devcontainer/start-dev.sh +++ b/.devcontainer/start-dev.sh @@ -1,4 +1,10 @@ #!/usr/bin/env bash -# Auto-start dev servers when devcontainer starts. -# Delegates to dev-servers manager for process tracking. -exec /workspace/.devcontainer/dev-servers.sh start +# Print available commands on container start. +set -euo pipefail + +echo "Dev servers ready:" +echo " ui # global-mode dashboard → :5173" +echo " ui -p # project-mode dashboard → :5173" +echo " ui stop # stop dashboard" +echo " docs # documentation site → :3000" +echo " docs stop # stop docs" diff --git a/website/docs/guides/docker-sandbox.md b/website/docs/guides/docker-sandbox.md index 113fbdaa3..4c78ea9d3 100644 --- a/website/docs/guides/docker-sandbox.md +++ b/website/docs/guides/docker-sandbox.md @@ -44,6 +44,7 @@ Command mapping: |---|---|---| | `test-docker` | `mise run test:docker` | `make test-docker` | | `test-docker-online` | `mise run test:docker:online` | `make test-docker-online` | +| **`playground`** | **`mise run playground`** | **`make playground`** | | `sandbox-up` | `mise run sandbox:up` | `make sandbox-up` | | `sandbox-shell` | `mise run sandbox:shell` | `make sandbox-shell` | | `sandbox-down` | `mise run sandbox:down` | `make sandbox-down` | @@ -91,13 +92,19 @@ mise run test:docker:online make test-docker-online ``` -### 3. Open a dedicated playground and explore all commands +### 3. Open a dedicated playground and explore all commands {#playground} + +One command to start and enter the playground: ```bash -mise run sandbox:up -mise run sandbox:shell -make sandbox-up -make sandbox-shell +make playground +mise run playground +``` + +Or start and enter separately: + +```bash +make sandbox-up && make sandbox-shell ``` Inside the playground, `skillshare` and `ss` are ready. Both global mode and project mode are pre-initialized: @@ -119,31 +126,14 @@ skillshare list skillshare sync --dry-run ``` -To launch the project mode web dashboard, use the built-in alias: +To launch the web dashboard, use the built-in aliases: ```bash -skillshare-ui-p # starts project mode dashboard on port 19420 +skillshare-ui # global mode dashboard → http://localhost:19420 +skillshare-ui-p # project mode dashboard (~/demo-project) → http://localhost:19420 ``` -Or run the command manually from the demo project directory: - -```bash -cd ~/demo-project -skillshare ui -p --host 0.0.0.0 --no-open -``` - -Then open `http://localhost:19420` on your host machine. - -### Web UI in the Playground - -The playground container includes pre-built frontend assets and maps port 19420 to the host. Both global and project mode are pre-initialized, so you can launch the dashboard immediately: - -```bash -skillshare-ui # global mode dashboard -skillshare-ui-p # project mode dashboard (~/demo-project) -``` - -Then open `http://localhost:19420` in your host browser. Use `--host 0.0.0.0` because the container's `127.0.0.1` is not reachable from the host. +Then open `http://localhost:19420` on your host machine (port is mapped via Docker Compose). ### GitHub Token (for Search) @@ -323,7 +313,7 @@ The devcontainer reuses the same `docker/sandbox/Dockerfile` as the sandbox, so - Ports forwarded: `19420` (Web UI), `5173` (Vite HMR), `3000` (Docusaurus) - Source code mounted at `/workspace` - **Pre-configured demo environment** — same as the interactive playground: - - Shortcut commands in PATH (`ss`, `ui`, `ui-p`, `docs`, `dev-servers`) + - Shortcut commands in PATH (`ss`, `ui`, `docs`) - Frontend dependencies pre-installed (`ui/` and `website/`) - Global demo skills (audit examples, deploy checklist) - Custom audit rules (global + project) @@ -339,43 +329,26 @@ ss audit # run audit with custom rules cd ~/demo-project ss status # auto-detects project mode ss audit # project-level audit -ui-p # switch to project mode dashboard (:19420) +ui -p # switch API to project mode → http://localhost:5173 ``` ### Frontend development -All three dev servers start automatically when the container opens: - -| Port | Service | What it serves | -|------|---------|----------------| -| `19420` | Go API server | REST API backend | -| `5173` | Vite | React UI with hot reload | -| `3000` | Docusaurus | Documentation site with hot reload | - -Open `http://localhost:5173` (UI) or `http://localhost:3000` (docs) in your host browser — they're ready immediately. -These URLs are available via Dev Containers port forwarding (no fixed host port bind in `.devcontainer/docker-compose.yml`). - -**Managing dev servers:** +| Port | Service | Command | +|------|---------|---------| +| `5173` | Vite (React UI + HMR) | `ui` or `ui -p` | +| `19420` | Go API backend | started by `ui` / `ui -p` | +| `3000` | Docusaurus | `docs` | ```bash -dev-servers status # check which servers are running -dev-servers restart # restart all -dev-servers restart vite # restart just Vite -dev-servers stop docusaurus # stop just Docusaurus -dev-servers logs api # tail Go API server log +ui # global mode: API + Vite → http://localhost:5173 +ui -p # project mode: API + Vite → http://localhost:5173 +ui stop # stop API + Vite +docs # documentation site → http://localhost:3000 +docs stop # stop Docusaurus ``` -Servers shut down automatically when the container stops and restart on the next container start. - -### Running the Web UI inside the container - -```bash -ui # global mode dashboard (auto-started by dev-servers) -ui-p # switch to project mode (stops global, Ctrl-C to return) -docs # open documentation site (:3000) - -# VS Code auto-forwards port 19420 → open http://localhost:19420 -``` +`ui` starts both the Go API backend (port 19420, background) and Vite dev server (port 5173, HMR). Switching between `ui` and `ui -p` automatically restarts the API in the new mode. VS Code auto-forwards ports to your host browser. ### Running tests