feat(docker): auto delegate scripts to docker

.gitignore

@@ -36,7 +36,7 @@ build/
 install/
 
 # Doxygen
-html/
+docs/generated/
 
 # Testing
 Testing/

docs/Doxyfile

@@ -68,7 +68,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       =
+OUTPUT_DIRECTORY       = docs/generated
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format

scripts/build.sh

@@ -5,24 +5,35 @@ set -e
 # Build the project using CMake
 #
 # Builds in Debug mode by default and installs to the install/ directory.
+# When run outside the container, delegates execution to Docker automatically.
 #
 # Usage:
 #   ./scripts/build.sh
 ###############################################################################
 
-# Set build directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/env.sh"
+source "$SCRIPT_DIR/docker/exec.sh"
+delegate_to_container "$@"
+
+# ---------------------------------------------------------------------------
+# Build
+# ---------------------------------------------------------------------------
+cd "$PROJECT_ROOT"
+
 BUILD_DIR="build"
 INSTALL_DIR="install"
 
-# Create and enter build directory
 mkdir -p "$BUILD_DIR"
 cd "$BUILD_DIR"
 
-# Run CMake with Debug build type by default (for development)
-cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX="../$INSTALL_DIR" ..
+log_step "Configuring CMake (Debug)..."
+cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX="${PROJECT_ROOT}/$INSTALL_DIR" "$PROJECT_ROOT"
 
-# Build all targets with all cores
+log_step "Building with $(nproc) cores..."
 make -j"$(nproc)"
 
-# Install to ../install
+log_step "Installing to ${PROJECT_ROOT}/$INSTALL_DIR"
 make install
+
+log_info "Build complete."

scripts/coverage.sh

@@ -5,44 +5,46 @@ set -e
 # Build and run code coverage analysis
 #
 # Builds with coverage enabled, runs tests, and generates HTML coverage report.
+# When run outside the container, delegates execution to Docker automatically.
 #
 # Usage:
 #   ./scripts/coverage.sh
 ###############################################################################
 
-# Set build directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/env.sh"
+source "$SCRIPT_DIR/docker/exec.sh"
+delegate_to_container "$@"
+
+# ---------------------------------------------------------------------------
+# Coverage
+# ---------------------------------------------------------------------------
+cd "$PROJECT_ROOT"
+
 BUILD_DIR="build"
 INSTALL_DIR="install"
 
-echo "Building with code coverage enabled..."
-
-# Create and enter build directory
 mkdir -p "$BUILD_DIR"
 cd "$BUILD_DIR"
 
-# Run CMake with coverage enabled
-cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON -DCMAKE_INSTALL_PREFIX="../$INSTALL_DIR" ..
+log_step "Configuring CMake with coverage enabled..."
+cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON -DCMAKE_INSTALL_PREFIX="${PROJECT_ROOT}/$INSTALL_DIR" "$PROJECT_ROOT"
 
-# Build all targets with all cores
+log_step "Building with $(nproc) cores..."
 make -j"$(nproc)"
 
-# Run tests to generate coverage data
+log_step "Running tests..."
 make test
 
-# Generate coverage report with lcov
-echo "Generating coverage report..."
-export LC_ALL=C  # Fix locale warnings
+log_step "Generating coverage report..."
+export LC_ALL=C
 lcov --capture --directory . --output-file coverage.info --ignore-errors mismatch
-lcov --remove coverage.info '/usr/*' --output-file coverage.info --ignore-errors unused  # Remove system files
-lcov --remove coverage.info '*/build/*' --output-file coverage.info --ignore-errors unused  # Remove build files
-lcov --remove coverage.info '*/tests/*' --output-file coverage.info --ignore-errors unused  # Remove test files
-lcov --remove coverage.info '*/_deps/*' --output-file coverage.info --ignore-errors unused  # Remove external deps
+lcov --remove coverage.info '/usr/*' --output-file coverage.info --ignore-errors unused
+lcov --remove coverage.info '*/build/*' --output-file coverage.info --ignore-errors unused
+lcov --remove coverage.info '*/tests/*' --output-file coverage.info --ignore-errors unused
+lcov --remove coverage.info '*/_deps/*' --output-file coverage.info --ignore-errors unused
 
-# Generate HTML report
 genhtml coverage.info --output-directory coverage_report
 
-echo "Coverage report generated in build/coverage_report/"
-echo "Open build/coverage_report/index.html in your browser to view the report"
-
-# Optional: Install the project
-# make install
+log_info "Coverage report generated in build/coverage_report/"
+log_info "Open build/coverage_report/index.html in your browser to view the report."

scripts/docker/exec.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+
+###############################################################################
+# Container delegation for project scripts
+#
+# When a script is invoked outside the container, this module re-executes it
+# inside a disposable Docker container (docker run --rm) and exits.
+# If already inside the container, it returns immediately and the calling
+# script continues as normal.
+#
+# How it works:
+#
+#   Host shell                            Container shell
+#   ----------                            ----------------
+#   ./scripts/build.sh
+#     source env.sh
+#     source docker/exec.sh
+#     delegate_to_container
+#       docker run --rm ... build.sh  -->  ./scripts/build.sh
+#       exit $?                              source env.sh
+#                                            source docker/exec.sh
+#                                            delegate_to_container
+#                                              sees /.dockerenv
+#                                              return 0
+#                                            cmake ...
+#                                            make ...
+#                                         <-- exits (container destroyed)
+#
+# The host starts a subprocess (docker run) that runs the SAME script from
+# scratch. The second invocation detects /.dockerenv, skips delegation,
+# and executes the real work. The host waits for the exit code and forwards it.
+# The container is destroyed automatically after the script finishes (--rm).
+#
+# Requires env.sh to be sourced first (for logging helpers and PROJECT_ROOT).
+#
+# Usage (from any project script, after sourcing env.sh):
+#   source "$SCRIPT_DIR/docker/exec.sh"
+#   delegate_to_container "$@"
+###############################################################################
+
+IMAGE_NAME="cpp-dev:latest"
+CONTAINER_WORKDIR="/workspaces/${PROJECT_NAME}"
+
+delegate_to_container() {
+    # Already inside the container -- nothing to do
+    if [ -f /.dockerenv ]; then
+        return 0
+    fi
+
+    # Resolve the calling script path relative to project root (portable)
+    local caller_script="${BASH_SOURCE[1]}"
+    local script_absolute
+    script_absolute="$(cd "$(dirname "$caller_script")" && pwd)/$(basename "$caller_script")"
+    local script_relative="${script_absolute#"$PROJECT_ROOT"/}"
+
+    if [ "$script_relative" = "$script_absolute" ]; then
+        log_error "Script '${caller_script}' is not under PROJECT_ROOT '${PROJECT_ROOT}'."
+        return 1
+    fi
+
+    log_docker "Running outside container -- delegating to Docker..."
+
+    # Build the image if it does not exist yet
+    if ! docker image inspect "$IMAGE_NAME" &> /dev/null; then
+        log_docker "Image '${IMAGE_NAME}' not found. Building it first..."
+        "${PROJECT_ROOT}/scripts/docker/build_image.sh"
+    fi
+
+    # Run the script inside a disposable container
+    docker run --rm \
+        --hostname cpp-devcontainer \
+        --env "HOST_UID=$(id -u)" \
+        --env "HOST_GID=$(id -g)" \
+        --env TERM=xterm-256color \
+        --volume "$PROJECT_ROOT:${CONTAINER_WORKDIR}" \
+        --workdir "${CONTAINER_WORKDIR}" \
+        "$IMAGE_NAME" \
+        bash "${CONTAINER_WORKDIR}/${script_relative}" "$@"
+
+    exit $?
+}

scripts/docs.sh

@@ -5,18 +5,25 @@ set -e
 # Generate Doxygen documentation
 #
 # Generates HTML documentation from source code comments.
+# When run outside the container, delegates execution to Docker automatically.
 #
 # Usage:
 #   ./scripts/docs.sh
 ###############################################################################
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
-DOCS_DIR="${PROJECT_ROOT}/docs"
+source "$SCRIPT_DIR/env.sh"
+source "$SCRIPT_DIR/docker/exec.sh"
+delegate_to_container "$@"
 
-echo "[INFO] Generating Doxygen documentation..."
-echo "[INFO] Doxygen version: $(doxygen --version)"
+# ---------------------------------------------------------------------------
+# Documentation
+# ---------------------------------------------------------------------------
+cd "$PROJECT_ROOT"
 
-# Run doxygen from project root
-doxygen "$DOCS_DIR/Doxyfile"
+log_info "Generating Doxygen documentation..."
+log_info "Doxygen version: $(doxygen --version)"
 
+doxygen docs/Doxyfile
+
+log_info "Documentation generation complete."

scripts/env.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+
+###############################################################################
+# Environment setup for all project scripts
+#
+# Provides:
+#   - Colored output and logging helpers
+#   - Project path resolution
+#
+# Usage (source from other scripts):
+#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+#   source "$SCRIPT_DIR/env.sh"
+###############################################################################
+
+# ==============================================================================
+# Color definitions (disabled when output is not a terminal)
+# ==============================================================================
+if [ -t 1 ]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    CYAN='\033[0;36m'
+    BOLD='\033[1m'
+    RESET='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    CYAN=''
+    BOLD=''
+    RESET=''
+fi
+
+# ==============================================================================
+# Logging helpers
+# ==============================================================================
+log_info()    { echo -e "${GREEN}[INFO]${RESET} $*"; }
+log_warn()    { echo -e "${YELLOW}[WARN]${RESET} $*"; }
+log_error()   { echo -e "${RED}[ERROR]${RESET} $*"; }
+log_step()    { echo -e "${CYAN}[STEP]${RESET} $*"; }
+log_docker()  { echo -e "${BLUE}[CONTAINER]${RESET} $*"; }
+
+# ==============================================================================
+# Project paths
+#
+# SCRIPT_DIR must be set by the calling script before sourcing env.sh.
+# ==============================================================================
+if [ -z "${SCRIPT_DIR:-}" ] || [ ! -d "$SCRIPT_DIR" ]; then
+    echo "[ERROR] SCRIPT_DIR is not set or does not exist. Set it before sourcing env.sh." >&2
+    return 1
+fi
+
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+PROJECT_NAME="$(basename "$PROJECT_ROOT")"

scripts/format.sh

@@ -5,22 +5,27 @@ set -e
 # Format all C++ source/header files using clang-format
 #
 # Formats all C++ files in the project according to .clang-format config.
+# When run outside the container, delegates execution to Docker automatically.
 #
 # Usage:
 #   ./scripts/format.sh          - Format files in-place
 #   ./scripts/format.sh --check  - Check formatting without modifying files
 ###############################################################################
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+source "$SCRIPT_DIR/env.sh"
+source "$SCRIPT_DIR/docker/exec.sh"
+delegate_to_container "$@"
 
-# Check if --check flag is passed
+# ---------------------------------------------------------------------------
+# Format
+# ---------------------------------------------------------------------------
 CHECK_MODE=false
 if [[ "$1" == "--check" ]]; then
     CHECK_MODE=true
-    echo "[INFO] Running clang-format in check mode (no modifications)..."
+    log_info "Running clang-format in check mode (no modifications)..."
 else
-    echo "[INFO] Running clang-format on source files..."
+    log_info "Running clang-format on source files..."
 fi
 
 EXTENSIONS=("*.cpp" "*.hpp" "*.cc" "*.h" "*.cxx" "*.hxx")
@@ -32,17 +37,17 @@ for ext in "${EXTENSIONS[@]}"; do
     for f in $FILES; do
         FOUND=true
         if $CHECK_MODE; then
-            echo "Checking $f"
+            log_step "Checking $f"
             clang-format --dry-run --Werror "$f"
         else
-            echo "Formatting $f"
+            log_step "Formatting $f"
             clang-format -i "$f"
         fi
     done
 done
 
 if ! $FOUND; then
-    echo "[INFO] No files found to format."
+    log_warn "No files found to format."
 else
-    echo "[INFO] clang-format complete."
+    log_info "clang-format complete."
 fi

scripts/lint.sh

@@ -5,24 +5,35 @@ set -e
 # Run clang-tidy static analysis
 #
 # Runs clang-tidy over all C++ source files using compile_commands.json.
+# When run outside the container, delegates execution to Docker automatically.
 #
 # Usage:
 #   ./scripts/lint.sh
 ###############################################################################
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/env.sh"
+source "$SCRIPT_DIR/docker/exec.sh"
+delegate_to_container "$@"
+
+# ---------------------------------------------------------------------------
+# Lint
+# ---------------------------------------------------------------------------
+cd "$PROJECT_ROOT"
+
 BUILD_DIR="build"
 TIDY_BIN=$(command -v clang-tidy || true)
 
 if [ -z "$TIDY_BIN" ]; then
-    echo "[ERROR] clang-tidy not found. Install it first."
+    log_error "clang-tidy not found. Install it first."
     exit 1
 fi
 
-echo "[INFO] Running clang-tidy over source files..."
+log_info "Running clang-tidy over source files..."
 
 find src/ tests/ -type f \( -name '*.cpp' -o -name '*.cxx' -o -name '*.cc' \) | while read -r file; do
-    echo "[TIDY] $file"
+    log_step "$file"
     clang-tidy "$file" -p "$BUILD_DIR" || true
 done
 
-echo "[INFO] clang-tidy lint complete."
+log_info "clang-tidy lint complete."