feat(docs): enhance documentation of included tools and optimizations

- Updated repository overview to reflect a comprehensive suite of included development and operations tools.
- Added details about pre-installed tools in the base image to avoid redundant installations.
- Introduced best practices for tool installation and verification to improve efficiency and maintainability.
- Changed JSON/YAML tools installation script to a verification script, confirming the availability of pre-installed tools.

This enhances clarity for users regarding the environment setup processes.

Author: winromulus

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository Overview
 
-This repository contains Docker images for GitHub Actions self-hosted runners with additional tools pre-installed. The main image is based on the official GitHub Actions runner image and includes Python, PowerShell, Azure CLI, AzCopy, and Ansible.
+This repository contains Docker images for GitHub Actions self-hosted runners with additional tools pre-installed. The main image is based on the official GitHub Actions runner image and includes a comprehensive suite of development and operations tools including Python, PowerShell, Node.js, .NET SDK, Azure CLI, AzCopy, Ansible, Kubernetes tools, network utilities, and more.
 
 ## Architecture
 
@@ -108,10 +108,22 @@ The repository uses GitVersion for semantic versioning. The pipeline is triggere
 - `src/setup.yaml`: YAML configuration defining all installation steps
 - `src/setup.sh`: Main orchestrator that reads setup.yaml and executes steps
 - `src/scripts/`: Installation scripts for various tools
-  - `install-python.sh`: Installs Python3, pip, pip3, and pipx
+  - `install-coreutils.sh`: Verifies GNU coreutils (pre-installed)
+  - `install-file-tools.sh`: Installs file utilities (file, tree, time)
+  - `install-archive-tools.sh`: Installs compression tools (p7zip, zip)
+  - `install-python.sh`: Installs pip and Python development tools
   - `install-powershell.sh`: Installs PowerShell Core
+  - `install-nodejs.sh`: Installs Node.js and npm
   - `install-azure-cli.sh`: Installs Azure CLI
   - `install-azcopy.sh`: Installs AzCopy with architecture detection
+  - `install-ansible.sh`: Installs Ansible via pip
+  - `install-docker-tools.sh`: Installs Docker Compose plugin
+  - `install-json-tools.sh`: Verifies jq and yq tools
+  - `install-kubernetes-tools.sh`: Installs kubectl, helm, kustomize
+  - `install-yamllint.sh`: Installs yamllint
+  - `install-github-cli.sh`: Installs GitHub CLI
+  - `install-dotnet-sdk.sh`: Installs .NET SDK (LTS and latest)
+  - `install-network-tools.sh`: Installs comprehensive network utilities
 - `.github/workflows/pipeline.yaml`: Main CI/CD pipeline
 - `GitVersion.yaml`: Semantic versioning configuration
 
@@ -158,4 +170,28 @@ 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
+4. Verify architecture-specific logic for ARM64 vs AMD64
+
+## Base Image Optimization
+
+The base GitHub Actions runner image already includes many common tools. Before adding new tools, check if they're pre-installed:
+
+### Pre-installed Tools (Do Not Re-install)
+- **Core utilities**: curl, wget, git, tar, unzip, sudo
+- **Python 3**: Python interpreter (but not pip)
+- **Docker**: Docker engine with Docker Buildx
+- **JSON processing**: jq
+- **SSH tools**: ssh, scp, openssh-client
+- **Build essentials**: gcc, make, build-essential
+
+### Verification Scripts
+Some scripts only verify pre-installed tools rather than installing them:
+- `install-coreutils.sh`: Verifies GNU coreutils
+- `install-json-tools.sh`: Verifies jq (pre-installed) and yq (installed in Dockerfile)
+
+### Installation Best Practices
+1. Always check if a tool is pre-installed before adding installation logic
+2. Use verification-only scripts for pre-installed tools
+3. Group related tools in single installation scripts
+4. Minimize apt-get update calls by grouping installations
+5. Clean package caches after installation to reduce image size

README.md

@@ -40,6 +40,19 @@ docker run -d \
 
 ## Included Software
 
+### Pre-installed in Base Image
+The following tools are already available in the GitHub Actions runner base image:
+- **Python 3** - Python interpreter
+- **Git** - Version control system
+- **Docker** with **Docker Buildx** - Container platform
+- **jq** - JSON processor
+- **curl** - Data transfer tool
+- **SSH/SCP** - Secure shell and copy
+- **tar** - Archive utility
+- **unzip** - ZIP extraction
+- **sudo** - Privilege escalation
+- **Core Unix tools** - find, grep, sed, awk, perl, etc.
+
 ### Core Utilities
 - **GNU Coreutils** - Essential Unix utilities (ls, cp, mv, cat, etc.)
 - **File Utilities**
@@ -71,15 +84,16 @@ docker run -d \
 - **Kustomize** - Kubernetes configuration management (latest)
 
 ### Development Tools
-- **Git** - Version control (latest from official PPA)
+- **Git** - Version control (pre-installed in base image)
 - **GitHub CLI** (`gh`) - GitHub operations (latest)
-- **jq** - JSON processor
+- **jq** - JSON processor (pre-installed in base image)
 - **yq** - YAML processor (latest)
 - **yamllint** - YAML linter (latest from pip)
 
 ### Archive & Compression Tools
-- **tar** - Tape archive utility
-- **zip/unzip** - ZIP archive utilities
+- **tar** - Tape archive utility (pre-installed in base image)
+- **unzip** - ZIP decompression (pre-installed in base image)
+- **zip** - ZIP compression
 - **p7zip-full** (7z) - 7-Zip archiver
 
 ### Network Tools
@@ -98,8 +112,8 @@ docker run -d \
   - `netstat` - Network statistics
   - `route` - Routing table manipulation
 - **Connection Tools**
-  - `ssh` - Secure Shell client
-  - `scp` - Secure copy
+  - `ssh` - Secure Shell client (pre-installed in base image)
+  - `scp` - Secure copy (pre-installed in base image)
   - `ftp` - File Transfer Protocol client
   - `telnet` - Telnet client
   - `netcat` (`nc`) - Network debugging

src/Dockerfile

@@ -3,10 +3,10 @@ FROM ghcr.io/actions/actions-runner:2.327.1
 USER root
 
 # Install required dependencies
+# Note: curl is already in base image, but wget is needed
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
     wget \
-    curl \
     ca-certificates \
     && rm -rf /var/lib/apt/lists/*
 

src/scripts/install-json-tools.sh

@@ -1,29 +1,30 @@
 #!/bin/bash
 
-# Install jq (yq is already installed in the Dockerfile)
+# Verify JSON/YAML tools
+# Note: Both jq and yq are already available
+# - jq is pre-installed in the base image
+# - yq is installed in the Dockerfile
 
-echo "Installing JSON/YAML tools..."
+echo "Verifying JSON/YAML tools..."
 
-# Install jq
-apt-get update
-apt-get install -y --no-install-recommends jq
-
-# Verify jq installation
-echo "Verifying jq installation..."
+# Verify jq is available (pre-installed in base image)
+echo "Checking jq installation..."
 if ! command -v jq &> /dev/null; then
-    echo "ERROR: jq command not found after installation"
+    echo "ERROR: jq command not found (should be pre-installed)"
     exit 1
 fi
 echo "jq version:"
 jq --version
 
 # Verify yq is available (installed in Dockerfile)
-echo "Verifying yq installation..."
+echo ""
+echo "Checking yq installation..."
 if ! command -v yq &> /dev/null; then
     echo "ERROR: yq command not found"
     exit 1
 fi
 echo "yq version:"
 yq --version
 
-echo "JSON/YAML tools installation completed successfully!"
+echo ""
+echo "JSON/YAML tools verification completed successfully!"

src/scripts/install-network-tools.sh

@@ -5,6 +5,7 @@
 echo "Installing network tools..."
 
 # Install network packages
+# Note: openssh-client (ssh, scp) is already in base image
 apt-get update
 apt-get install -y --no-install-recommends \
     dnsutils \
@@ -14,7 +15,6 @@ apt-get install -y --no-install-recommends \
     iproute2 \
     net-tools \
     netcat \
-    openssh-client \
     ftp \
     telnet \
     sshpass

src/scripts/install-python.sh

@@ -1,11 +1,11 @@
 #!/bin/bash
 
-# Install Python and pip
+# Install pip and Python development tools
+# Note: Python3 is already installed in the base image
 
-# Update packages and install Python3 and pip
+# Update packages and install pip and development tools
 apt-get update
 apt-get install -y --no-install-recommends \
-    python3 \
     python3-pip \
     python3-venv \
     python3-dev

src/setup.yaml

@@ -17,7 +17,7 @@ setup:
 
     - name: "Install Python and pip"
       script: "scripts/install-python.sh"
-      description: "Installs Python3 and pip"
+      description: "Installs pip and Python dev tools (Python3 is pre-installed)"
 
     - name: "Install PowerShell"
       script: "scripts/install-powershell.sh"
@@ -43,9 +43,9 @@ setup:
       script: "scripts/install-docker-tools.sh"
       description: "Installs Docker Compose plugin"
 
-    - name: "Install JSON/YAML tools"
+    - name: "Verify JSON/YAML tools"
       script: "scripts/install-json-tools.sh"
-      description: "Installs jq (yq is already installed)"
+      description: "Verifies jq (pre-installed) and yq (installed in Dockerfile)"
 
     - name: "Install Kubernetes tools"
       script: "scripts/install-kubernetes-tools.sh"