feat: update README, enhance setup scripts, and add dev utilities for improved workflow

setup.sh

@@ -11,14 +11,29 @@ warn() { echo -e "${YELLOW}[!]${NC} $*"; }
 die() { echo -e "${RED}[x] FATAL:${NC} $*" >&2; exit 1; }
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ENV_FILE="$ROOT_DIR/backend/.env"
+BACKEND_DIR="$ROOT_DIR/backend"
+FRONTEND_DIR="$ROOT_DIR/frontend"
+ENV_FILE="$BACKEND_DIR/.env"
 
-compose() {
-    docker compose --env-file "$ENV_FILE" -f "$ROOT_DIR/docker-compose.yml" "$@"
+require_command() {
+    command -v "$1" >/dev/null 2>&1 || die "Missing required command: $1"
 }
 
-playground() {
-    docker compose -f "$ROOT_DIR/playground/docker-compose.yml" "$@"
+ensure_uv() {
+    if command -v uv >/dev/null 2>&1; then
+        return
+    fi
+
+    info "Installing uv..."
+    require_command curl
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    export PATH="$HOME/.local/bin:$PATH"
+    command -v uv >/dev/null 2>&1 || die "uv installed but not found in PATH"
+}
+
+ensure_python() {
+    info "Ensuring Python 3.14 is available via uv..."
+    uv python install 3.14
 }
 
 sync_env_values() {
@@ -35,11 +50,12 @@ sync_env_values() {
 
 ensure_env() {
     if [[ -f "$ENV_FILE" ]]; then
+        sync_env_values
         return
     fi
 
     warn "backend/.env not found, creating it from backend/.env.example"
-    cp "$ROOT_DIR/backend/.env.example" "$ENV_FILE"
+    cp "$BACKEND_DIR/.env.example" "$ENV_FILE"
 
     local mongo_pass jwt_secret auth_pass
     mongo_pass=$(openssl rand -hex 8)
@@ -56,74 +72,58 @@ ensure_env() {
     info "AUTH_PASSWORD: $auth_pass"
 }
 
-install_service() {
-    mkdir -p ~/.config/systemd/user
-    cat > ~/.config/systemd/user/theplug.service <<EOF
-[Unit]
-Description=thePlug stack
-After=network.target
+prepare_backend() {
+    info "Installing backend dependencies..."
+    (
+        cd "$BACKEND_DIR"
+        uv sync --python 3.14
+    )
+}
 
-[Service]
-Type=oneshot
-RemainAfterExit=yes
-WorkingDirectory=$ROOT_DIR
-ExecStart=/usr/bin/docker compose --env-file $ENV_FILE -f $ROOT_DIR/docker-compose.yml up -d
-ExecStop=/usr/bin/docker compose --env-file $ENV_FILE -f $ROOT_DIR/docker-compose.yml down
+prepare_frontend() {
+    require_command npm
+    info "Installing frontend dependencies..."
+    (
+        cd "$FRONTEND_DIR"
+        npm install
+        npm run build
+    )
+}
 
-[Install]
-WantedBy=default.target
+prepare_docker_assets() {
+    require_command docker
+    info "Preparing Docker assets..."
+    docker compose --env-file "$ENV_FILE" -f "$ROOT_DIR/docker-compose.yml" pull mongodb
+    docker compose --env-file "$ENV_FILE" -f "$ROOT_DIR/docker-compose.yml" build frontend
+}
+
+print_next_steps() {
+    cat <<EOF
+
+Setup complete.
+
+Next commands:
+  ./run.sh mongo up
+  ./run.sh backend
+  ./run.sh frontend up
+
+Optional:
+  ./dev.sh mongo up
+  ./dev.sh backend
+  ./dev.sh frontend
+  ./dev.sh services list
 EOF
-    systemctl --user daemon-reload
-    systemctl --user enable theplug
-    info "systemd user service installed"
 }
 
-start_stack() {
+main() {
+    require_command openssl
+    ensure_uv
+    ensure_python
     ensure_env
-    sync_env_values
-    info "Building and starting backend, frontend and MongoDB..."
-    compose up -d --build
-    info "Backend:  http://localhost:$(grep -E '^API_PORT=' "$ENV_FILE" | cut -d '=' -f2 || echo 3671)"
-    info "Frontend: http://localhost:$(grep -E '^FRONTEND_PORT=' "$ENV_FILE" | cut -d '=' -f2 || echo 5173)"
+    prepare_backend
+    prepare_frontend
+    prepare_docker_assets
+    print_next_steps
 }
 
-start_deps() {
-    ensure_env
-    sync_env_values
-    info "Starting MongoDB for host-backend testing..."
-    compose up -d mongodb
-    info "Now run these on the host:"
-    info "  npm run dev:backend"
-    info "  npm run dev:frontend"
-}
-
-start_playground() {
-    info "Starting local playground upstream service..."
-    playground up -d
-    info "Playground service: http://127.0.0.1:9081"
-}
-
-if [[ "${1:-}" == "service" ]]; then
-    ensure_env
-    install_service
-    systemctl --user start theplug
-    exit 0
-fi
-
-if [[ "${1:-}" == "deps" ]]; then
-    start_deps
-    exit 0
-fi
-
-if [[ "${1:-}" == "playground" ]]; then
-    start_playground
-    exit 0
-fi
-
-if [[ -d "/srv/theplug" && "$ROOT_DIR" != "/srv/theplug" ]]; then
-    info "thePlug found in /srv/theplug, switching there"
-    cd /srv/theplug
-    exec ./setup.sh "$@"
-fi
-
-start_stack
+main "$@"