Enhance INCLUDE command to support remote Pifiles with caching support

README.md

@@ -167,10 +167,21 @@ Please take a look and feel free to submit your own examples if they are coverin
 
 ### Commands
 #### Stage independent
-##### `INCLUDE PATH_TO_PIFILE`
+##### `INCLUDE PATH_TO_PIFILE`, `INCLUDE URL`
 `INCLUDE` includes the provided Pifile in the current one for modularity and re-use.
 The included file _has_ to have a `.Pifile` extension which need not be specified.
 
+`INCLUDE` can also accept URLs to remote Pifiles, such as raw GitHub URLs, allowing you to use public modules directly.
+Remote Pifiles are cached locally (see `--cache` option) and will be reused on subsequent runs.
+
+```
+# Include a local module
+INCLUDE modules/setup
+
+# Include a remote module from GitHub (omits Pifile extension)
+INCLUDE https://raw.githubusercontent.com/user/repo/main/modules/module
+```
+
 #### 1. Setup Stage
 ##### `FROM PATH_TO_IMAGE [PARTITION_NO]`, `FROM URL [PARTITION_NO]`
 `FROM` sets the `SOURCE_IMG` variable to a target.

examples/Remote-Include-Example.Pifile

@@ -0,0 +1,16 @@
+# Example demonstrating remote INCLUDE functionality
+# This example shows how to include Pifiles from remote URLs (e.g., GitHub)
+
+FROM https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2023-02-22/2023-02-21-raspios-bullseye-arm64-lite.img.xz
+TO remote-include-example.img
+
+PUMP 100M
+
+# Example of including a remote module from a GitHub repository
+INCLUDE https://raw.githubusercontent.com/aniongithub/pi-bootstrap/refs/heads/main/modules/hostname.Pifile
+
+# Basic setup
+RUN apt-get update
+RUN apt-get install -y cowsay
+
+RUN raspi-config nonint do_ssh 0

stages/00-commands.sh

@@ -16,13 +16,41 @@ post_stage() {
   :
 }
 
-# INCLUDE sources the provided Pifile
+# INCLUDE sources the provided Pifile from a local path or remote URL.
+# For URLs, the file is downloaded to the cache and then sourced.
 #
 # Usage: INCLUDE path/to/pifile[.Pifile]
+#        INCLUDE https://example.com/path/to/pifile[.Pifile]
 INCLUDE() {
-  filename="${1%.*}"
+  local target="${1}"
+  local filename
+  local cached_file
+
+  # Check if it's a URL
+  if from_remote_valid "${target}"; then
+    # Download to cache
+    local url_path
+    url_path=$(echo "${target}" | sed 's/.*:\/\///')
+    cached_file="${PIMOD_CACHE}/${url_path}"
+
+    if [ -f "${cached_file}" ]; then
+      echo "Using cached Pifile: ${cached_file}"
+    else
+      echo "Fetching remote Pifile: ${target}"
+      mkdir -p "$(dirname "${cached_file}")"
+      wget --progress=dot:giga -O "${cached_file}" "${target}" || rm "${cached_file}"
+    fi
+
+    filename="${cached_file}"
+  else
+    # Local file - remove .Pifile extension if present
+    filename="${target%.*}"
+    filename="${filename}.Pifile"
+  fi
+
+  # Source the Pifile
   # shellcheck disable=SC1090
-  source "${filename}.Pifile"
+  source "${filename}"
 }
 
 # Stage 1x