Dev to master for LFS tests

.github/workflows/main.yml

@@ -18,6 +18,10 @@ jobs:
         with:
           lfs: true # we use LFS to store large files (e.g. data.nc)
 
+      - name: Verify LFS test asset (data.nc)
+        run: |
+          bash ./tools/preflight/verify-lfs.sh
+
       - name: Install Dependencies (Build + Test)
         run: |
           sudo apt-get update -y

README.md

@@ -44,6 +44,10 @@
 
 The easiest way to get started is often using Docker and the interactive console, via the **`forefire` command-line interpreter** 
 
+#### Windows note
+
+ForeFire targets Unix-like systems (Linux/macOS). On Windows, please use Docker Desktop or WSL2 to run the quick-start examples.
+
 1. Clone the repository
 
     ``` bash
@@ -52,26 +56,33 @@ The easiest way to get started is often using Docker and the interactive console
     cd forefire
     ```
 
-2. Build the Docker image 
+2. Verify Git LFS sample data (required for the quick-start examples)
+
+    ```bash
+    bash tools/preflight/verify-lfs.sh
+    ```
+    If this fails (e.g., `tests/runff/data.nc` is ~1 KB), install Git LFS and reclone the repo, or download the file from the GitHub web UI into `tests/runff/`.
+
+3. Build the Docker image 
 
     ```bash
     docker build . -t forefire:latest
     ```
 
-3. Run the container interactively
+4. Run the container interactively
 
     ```bash
     docker run -it --rm -p 8000:8000 --name ff_interactive forefire
     ```
-4. Inside the container navigate to test directory and launch the forefire console:
+5. Inside the container navigate to test directory and launch the forefire console:
     ```bash
     cd tests/runff
 
     # start the forefire console with the command
     forefire
     ```
 
-5. Inside the console launch an http server with listenHttp[] command
+6. Inside the console launch an http server with listenHttp[] command
 
     ```bash
     forefire> listenHTTP[]
@@ -82,7 +93,7 @@ The easiest way to get started is often using Docker and the interactive console
 
     This server provides a graphical user interface that you can access on your browser at http://localhost:8000/
 
-6. Run your first simulation
+7. Run your first simulation
 
     In ForeFire, running a simulation and viewing the result are separate commands. The UI guides you through this process.
     - **Step 1: Run the simulation script.** In the command input box, type `include[real_case.ff]` and click the **`Send`** button. The simulation will run on the server.

tools/preflight/verify-lfs.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Minimal preflight check for Git LFS assets used by quick-start tests
+# Verifies that tests/runff/data.nc is a real NetCDF file (by size) and, if available, via ncdump.
+
+PROJECT_ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")"/../.. && pwd)"
+DATA_FILE_REL="tests/runff/data.nc"
+DATA_FILE="${PROJECT_ROOT_DIR}/${DATA_FILE_REL}"
+
+if [[ ! -f "${DATA_FILE}" ]]; then
+  echo "ERROR: ${DATA_FILE_REL} not found. Did you fetch Git LFS files?"
+  echo "Hint: Install Git LFS and reclone, or download the file from GitHub UI into ${DATA_FILE_REL}."
+  exit 1
+fi
+
+# Cross-platform file size (Linux: stat -c, macOS: stat -f)
+if size_bytes=$(stat -c%s "${DATA_FILE}" 2>/dev/null); then
+  :
+elif size_bytes=$(stat -f%z "${DATA_FILE}" 2>/dev/null); then
+  :
+else
+  echo "WARNING: Could not determine file size via stat. Skipping size check."
+  size_bytes=0
+fi
+
+echo "Found ${DATA_FILE_REL} (size: ${size_bytes} bytes)"
+
+# Threshold: > 1 MB indicates not an LFS pointer
+MIN_BYTES=1000000
+if [[ "${size_bytes}" -lt "${MIN_BYTES}" ]]; then
+  echo "ERROR: ${DATA_FILE_REL} appears to be a Git LFS pointer (size ${size_bytes} bytes)."
+  echo "Fix: Install Git LFS and reclone the repository, or use 'git lfs fetch --all && git lfs checkout'."
+  exit 1
+fi
+
+if command -v ncdump >/dev/null 2>&1; then
+  if ! ncdump -k "${DATA_FILE}" >/dev/null 2>&1; then
+    echo "ERROR: ncdump failed to read ${DATA_FILE_REL}. The file may be corrupted."
+    exit 1
+  fi
+fi
+
+echo "OK: ${DATA_FILE_REL} looks valid."
+