chore: slightly more helpful and organized pnpm onboarding

Author: Spelkington

package.json

@@ -4,7 +4,7 @@
   "description": "A type-safe data engineering framework for .NET",
   "main": "index.js",
   "scripts": {
-    "postinstall": "bash scripts/post-pnpm-install-hook.sh",
+    "postinstall": "bash scripts/post-install/post-install.sh",
     "prepare": "husky"
   },
   "keywords": [

scripts/post-install/dependencies/chromium.sh

@@ -0,0 +1,24 @@
+# Sourced by ../post-install.sh.
+# ── chromium ──────────────────────────────────────────────────────────────────
+# Optional. Plotly's static image export (PNG/SVG via kaleido) launches a
+# headless Chromium under the hood. Without a Chromium-family browser on
+# PATH, Python flows that emit graph image outputs (e.g. FlowthruCoverage's
+# heatmap PNG) will fail at the image-export step.
+
+CHROMIUM_BIN=""
+for candidate in chromium chromium-browser google-chrome chrome; do
+  if command -v "$candidate" &>/dev/null; then
+    CHROMIUM_BIN="$candidate"
+    break
+  fi
+done
+
+if [ -n "$CHROMIUM_BIN" ]; then
+  CHROMIUM_VERSION=$("$CHROMIUM_BIN" --version 2>/dev/null | head -1)
+  ok "$CHROMIUM_VERSION  (via $CHROMIUM_BIN)"
+else
+  warn "chromium not found. Python flows that export Plotly graphs to PNG/SVG"
+  warn "(e.g. FlowthruCoverage's heatmap) may fail to produce image outputs"
+  warn "without a headless Chromium on PATH."
+  warn "Install: https://www.chromium.org/getting-involved/download-chromium/"
+fi

scripts/post-install/dependencies/dotnet-9.sh

@@ -0,0 +1,28 @@
+# Sourced by ../post-install.sh.
+# ── .NET 9 runtime ────────────────────────────────────────────────────────────
+# Optional but recommended. StrawberryShake.Server's MSBuild codegen invokes
+# a tool that ships only net8 and net9 binaries; on hosts running newer SDKs
+# (e.g. .NET 10), MSBuild still selects the net9 tool, which then requires the
+# .NET 9 *shared framework* on disk to launch. SDK-only installs of newer
+# .NET versions are not sufficient.
+#
+# Without this runtime, Flowthru.Extensions.GQL example projects
+# (e.g. KedroSpaceflightsGQL) will fail at build time with MSB3073 / exit 150.
+
+if command -v dotnet &>/dev/null; then
+  if dotnet --list-runtimes 2>/dev/null \
+       | grep -qE '^Microsoft\.NETCore\.App 9\.'; then
+    DOTNET9_VERSION=$(dotnet --list-runtimes 2>/dev/null \
+      | grep -E '^Microsoft\.NETCore\.App 9\.' \
+      | head -1 \
+      | awk '{print $2}')
+    ok "Microsoft.NETCore.App $DOTNET9_VERSION  (required for Flowthru.Extensions.GQL codegen)"
+  else
+    warn ".NET 9 runtime not found. The Flowthru.Extensions.GQL example projects"
+    warn "(e.g. KedroSpaceflightsGQL) will fail to build because StrawberryShake's"
+    warn "codegen tool ships only net8/net9 binaries and needs the .NET 9 shared"
+    warn "framework at build time."
+    warn "Download: https://dotnet.microsoft.com/download/dotnet/9.0"
+  fi
+fi
+# If dotnet itself is missing, the dotnet check has already warned.

scripts/post-install/dependencies/dotnet.sh

@@ -0,0 +1,26 @@
+# Sourced by ../post-install.sh.
+# ── dotnet ────────────────────────────────────────────────────────────────────
+# Required to build and test all Flowthru projects.
+# On success, runs 'dotnet restore' to prime the NuGet cache.
+
+REQUIRED_DOTNET_MAJOR=$(grep -o '"version":[[:space:]]*"[^"]*"' "$ROOT_DIR/global.json" \
+  | grep -o '[0-9][0-9]*' | head -1)
+
+if command -v dotnet &>/dev/null; then
+  DOTNET_VERSION=$(dotnet --version 2>/dev/null)
+  DOTNET_MAJOR=$(echo "$DOTNET_VERSION" | cut -d. -f1)
+
+  if [ "$DOTNET_MAJOR" -ge "$REQUIRED_DOTNET_MAJOR" ]; then
+    ok "dotnet $DOTNET_VERSION  (global.json requires .NET $REQUIRED_DOTNET_MAJOR+)"
+    echo ""
+    echo "  Running dotnet restore..."
+    dotnet restore "$ROOT_DIR"
+    ok "dotnet restore complete"
+  else
+    warn "dotnet $DOTNET_VERSION found, but .NET $REQUIRED_DOTNET_MAJOR+ is required (see global.json)."
+    warn "Download: https://dotnet.microsoft.com/download"
+  fi
+else
+  warn "dotnet not found. .NET $REQUIRED_DOTNET_MAJOR+ is required to build and test Flowthru."
+  warn "Download: https://dotnet.microsoft.com/download"
+fi

scripts/post-install/dependencies/java.sh

@@ -0,0 +1,10 @@
+# Sourced by ../post-install.sh.
+# ── java ──────────────────────────────────────────────────────────────────────
+# Required to run Spark-backed tests. Spark 4.1.1 requires JDK 17+.
+
+if command -v java &>/dev/null; then
+  JAVA_VERSION=$(java -version 2>&1 | head -1)
+  ok "java: $JAVA_VERSION"
+else
+  warn "java not found. JDK 17+ is required to run Spark-backed Flowthru tests."
+fi

scripts/post-install/dependencies/python.sh

@@ -0,0 +1,14 @@
+# Sourced by ../post-install.sh.
+# ── python ────────────────────────────────────────────────────────────────────
+# Required for the Flowthru.Extensions.Python extension and example projects.
+
+if command -v python3 &>/dev/null; then
+  PYTHON_VERSION=$(python3 --version 2>/dev/null | awk '{print $2}')
+  ok "python $PYTHON_VERSION"
+elif command -v python &>/dev/null; then
+  PYTHON_VERSION=$(python --version 2>/dev/null | awk '{print $2}')
+  ok "python $PYTHON_VERSION"
+else
+  warn "python not found. Python 3.10+ is required for the Flowthru Python extension and examples."
+  warn "Install via uv: https://docs.astral.sh/uv/  or  https://www.python.org/downloads/"
+fi

scripts/post-install/dependencies/spark.sh

@@ -0,0 +1,17 @@
+# Sourced by ../post-install.sh.
+# ── SPARK_HOME ────────────────────────────────────────────────────────────────
+# Required to run Spark-backed tests (Flowthru.Extensions.Spark.Tests).
+# Tests guard themselves with Assume checks and skip gracefully if unset.
+
+if [ -n "${SPARK_HOME:-}" ] && [ -d "$SPARK_HOME" ]; then
+  if [ -f "$SPARK_HOME/RELEASE" ]; then
+    SPARK_RELEASE=$(head -1 "$SPARK_HOME/RELEASE")
+    ok "SPARK_HOME=$SPARK_HOME  ($SPARK_RELEASE)"
+  else
+    ok "SPARK_HOME=$SPARK_HOME"
+  fi
+else
+  warn "SPARK_HOME is not set or does not point to a valid directory."
+  warn "Apache Spark 4.1.1 is required to run Spark-backed Flowthru tests."
+  warn "Download: https://spark.apache.org/downloads.html"
+fi

scripts/post-install/dependencies/uv.sh

@@ -0,0 +1,11 @@
+# Sourced by ../post-install.sh.
+# ── uv ────────────────────────────────────────────────────────────────────────
+# Required for Python-backed flows and the Flowthru.Extensions.Python test suite.
+
+if command -v uv &>/dev/null; then
+  UV_VERSION=$(uv --version 2>/dev/null | awk '{print $2}')
+  ok "uv $UV_VERSION"
+else
+  warn "uv not found. uv is required for Python-backed Flowthru flows and tests."
+  warn "Install: https://docs.astral.sh/uv/getting-started/installation/"
+fi

scripts/post-install/post-install.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Post-install hook for the Flowthru repo.
+# Sources each dependency check in ./dependencies/ in the order listed below.
+# Each subscript is sourced (not executed) so it inherits ROOT_DIR and the
+# ok/warn helpers defined here; subscripts are not intended to run standalone.
+set -euo pipefail
+
+POST_INSTALL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$POST_INSTALL_DIR/../.." && pwd)"
+DEPENDENCIES_DIR="$POST_INSTALL_DIR/dependencies"
+
+ok()   { echo "  [OK]  $*"; }
+warn() { echo "  [!!]  $*" >&2; }
+
+# Order is intentional: `dotnet-9` inspects runtimes only when `dotnet`
+# itself was found, so it must run after the base dotnet check.
+DEPENDENCIES=(
+  dotnet
+  dotnet-9
+  uv
+  python
+  java
+  spark
+  chromium
+)
+
+echo ""
+echo "Checking non-Node dependencies..."
+echo ""
+
+for dep in "${DEPENDENCIES[@]}"; do
+  # shellcheck source=/dev/null
+  source "$DEPENDENCIES_DIR/$dep.sh"
+  echo ""
+done