feat(setup): add Node.js and npm installation script

- Introduced a new script for installing Node.js and npm, enhancing the development environment.
- Updated the setup configuration to include the new installation step, allowing for easy tools management.
- Expanded documentation to detail the setup process and installation verification steps.

Author: winromulus

.claude/settings.local.json

@@ -10,7 +10,8 @@
       "Bash(docker inspect:*)",
       "WebFetch(domain:github.com)",
       "Bash(mv:*)",
-      "WebFetch(domain:learn.microsoft.com)"
+      "WebFetch(domain:learn.microsoft.com)",
+      "Bash(find:*)"
     ],
     "deny": []
   }

CLAUDE.md

@@ -14,6 +14,18 @@ This repository contains Docker images for GitHub Actions self-hosted runners wi
 - **Multi-Architecture Support**: Supports both AMD64 and ARM64 architectures
 - **CI/CD**: Uses GitHub Actions for automated building and releasing
 
+### Setup System Details
+
+The setup system reads `src/setup.yaml` and executes installation steps sequentially. Each step can either:
+- Execute a script file from `src/scripts/` directory
+- Run inline commands directly
+
+The orchestrator (`setup.sh`) provides:
+- Colored logging with timestamps
+- Step execution tracking
+- Error handling with proper exit codes
+- Support for both `script` and `command` step types
+
 ## Key Commands
 
 ### Building the Docker Image
@@ -24,25 +36,65 @@ docker build -t github-actions-runner -f src/Dockerfile src/
 
 # Build with specific platform
 docker buildx build --platform linux/amd64 -t github-actions-runner -f src/Dockerfile src/
+
+# Build multi-platform image
+docker buildx build --platform linux/amd64,linux/arm64 -t github-actions-runner -f src/Dockerfile src/
+
+# Build and load into local Docker (single platform only)
+docker buildx build --platform linux/amd64 --load -t github-actions-runner -f src/Dockerfile src/
+```
+
+### Testing the Image Locally
+
+```bash
+# Run the built image
+docker run --rm -it github-actions-runner bash
+
+# Test specific tools
+docker run --rm github-actions-runner python3 --version
+docker run --rm github-actions-runner pwsh --version
+docker run --rm github-actions-runner az --version
 ```
 
 ### Adding New Tools
 
 To add a new tool to the image:
-1. Create an installation script in `src/scripts/` (e.g., `install-newtool.sh`)
-2. Add a step to `src/setup.yaml`:
+
+1. **For complex installations**, create a script in `src/scripts/`:
+   ```bash
+   # src/scripts/install-newtool.sh
+   #!/bin/bash
+   set -euo pipefail
+   
+   # Architecture detection if needed
+   ARCH=$(uname -m)
+   case ${ARCH} in
+     x86_64) ARCH_SUFFIX="amd64" ;;
+     aarch64) ARCH_SUFFIX="arm64" ;;
+   esac
+   
+   # Installation logic here
+   ```
+
+2. Add the step to `src/setup.yaml`:
    ```yaml
    - name: "Install New Tool"
      script: "scripts/install-newtool.sh"
      description: "Description of what this installs"
    ```
-   OR use inline commands:
+
+3. **For simple installations**, use inline commands:
    ```yaml
    - name: "Install New Tool"
-     command: "apt-get install -y newtool"
+     command: "apt-get update && apt-get install -y newtool"
      description: "Description of what this installs"
    ```
 
+4. Make the script executable:
+   ```bash
+   chmod +x src/scripts/install-newtool.sh
+   ```
+
 ### GitHub Actions Workflow
 
 The repository uses GitVersion for semantic versioning. The pipeline is triggered on:
@@ -78,4 +130,32 @@ Images are published to:
 - Docker Hub: `emberstack/github-actions-runner`
 - GitHub Container Registry: `ghcr.io/emberstack/github-actions-runner`
 
-Both registries receive multi-architecture manifests supporting AMD64 and ARM64.
+Both registries receive multi-architecture manifests supporting AMD64 and ARM64.
+
+## Development Workflow
+
+### Making Changes
+
+1. **Modify installation scripts**: Edit files in `src/scripts/` for tool-specific changes
+2. **Update setup configuration**: Modify `src/setup.yaml` to add/remove/reorder steps
+3. **Test locally**: Build and run the image to verify changes
+4. **Commit with semantic versioning**: Use commit messages like:
+   - `feat: add new tool` (minor version bump)
+   - `fix: correct installation issue` (patch version bump)
+   - `feat!: breaking change` or `+semver:major` (major version bump)
+
+### CI/CD Pipeline Details
+
+The pipeline (`pipeline.yaml`) consists of:
+1. **Discovery**: Determines version and whether to build/release
+2. **Build**: Parallel builds for each architecture
+3. **Manifest**: Creates multi-arch manifests
+4. **Release**: Creates GitHub releases (main branch only)
+
+### Debugging Installation Issues
+
+When debugging tool installations:
+1. Check the colored output from `setup.sh` for the specific failing step
+2. Run the Docker build with `--progress=plain` for detailed output
+3. Test scripts individually inside a running container
+4. Verify architecture-specific logic for ARM64 vs AMD64

src/scripts/install-nodejs.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+
+# Install Node.js and npm
+# Uses NodeSource official setup script
+
+# Detect architecture
+ARCH=$(uname -m)
+
+echo "Installing Node.js and npm..."
+
+# Install prerequisites
+apt-get update
+apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl
+
+# Use NodeSource's official setup script for Node.js 20.x
+curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+
+# Install Node.js (includes npm)
+apt-get install -y nodejs
+
+# Verify Node.js installation
+echo "Verifying Node.js installation..."
+if ! command -v node &> /dev/null; then
+    echo "ERROR: node command not found after installation"
+    exit 1
+fi
+echo "Node.js version:"
+node --version
+
+# Verify npm installation
+echo "Verifying npm installation..."
+if ! command -v npm &> /dev/null; then
+    echo "ERROR: npm command not found after installation"
+    exit 1
+fi
+echo "npm version:"
+npm --version
+
+# Display architecture info
+echo "Installed on architecture: $ARCH"
+
+echo "Node.js and npm installation completed successfully!"

src/setup.yaml

@@ -11,6 +11,10 @@ setup:
       script: "scripts/install-powershell.sh"
       description: "Installs PowerShell Core"
 
+    - name: "Install Node.js and npm"
+      script: "scripts/install-nodejs.sh"
+      description: "Installs Node.js and npm package manager"
+      
     - name: "Install Azure CLI"
       script: "scripts/install-azure-cli.sh"
       description: "Installs Azure CLI"