feat(install): align all installers on platformdirs.user_data_dir

install.ps1

@@ -10,12 +10,15 @@
 #   2. Downloads volca-<version>-windows-amd64.zip from the GH Release.
 #   3. Downloads volca-data-<data-version>.tar.gz (reference data bundle).
 #   4. Verifies both against SHA256SUMS.
-#   5. Extracts to:
+#   5. Extracts to (matches platformdirs.user_data_dir("volca", appauthor=False)):
 #        $env:LOCALAPPDATA\volca\<version>\volca.exe
 #        $env:LOCALAPPDATA\volca\data\<data-version>\{flows.csv,...}
 #      and points $env:LOCALAPPDATA\volca\data\current at <data-version>.
+#      Same root as install.sh and pyvolca.download().
 #   6. Installs a thin shim at $env:LOCALAPPDATA\volca\bin\volca.cmd that
 #      sets VOLCA_DATA_DIR and execs the real binary.
+#
+# Override the install root with $env:VOLCA_HOME = 'C:\full\path'.
 # =============================================================================
 
 [CmdletBinding()]
@@ -26,7 +29,7 @@ param(
 $ErrorActionPreference = 'Stop'
 
 $Repo = 'ccomb/volca'
-$Prefix = if ($env:VOLCA_PREFIX) { $env:VOLCA_PREFIX } else { Join-Path $env:LOCALAPPDATA 'volca' }
+$Prefix = if ($env:VOLCA_HOME) { $env:VOLCA_HOME } else { Join-Path $env:LOCALAPPDATA 'volca' }
 $BinDir = Join-Path $Prefix 'bin'
 $Shim = Join-Path $BinDir 'volca.cmd'
 

install.sh

@@ -11,24 +11,25 @@
 #   2. Downloads volca-<version>-<platform>.tar.gz from the GH Release
 #   3. Downloads volca-data-<data-version>.tar.gz (the reference data bundle)
 #   4. Verifies both against SHA256SUMS
-#   5. Extracts to:
-#        ~/.local/share/volca/<version>/volca
-#        ~/.local/share/volca/data/<data-version>/{flows.csv,...}
-#      and points ~/.local/share/volca/data/current at <data-version>.
+#   5. Extracts to the OS-native user data dir (matches platformdirs):
+#        Linux:   ${XDG_DATA_HOME:-~/.local/share}/volca/<version>/volca
+#        macOS:   ~/Library/Application Support/volca/<version>/volca
+#      with the data bundle under <root>/data/<data-version>/ and a
+#      <root>/data/current symlink pointing at it.
 #   6. Installs a thin shim at ~/.local/bin/volca that sets VOLCA_DATA_DIR
 #      and execs the real binary. The shim makes the data-bundle layout
 #      invisible to users — they just `volca …`.
 #
+# Override the install root with VOLCA_HOME=/full/path (skips OS detection).
+#
 # Windows:
 #   This script aborts. Use install.ps1 (or download from GH Releases).
 # =============================================================================
 
 set -eu
 
 REPO="ccomb/volca"
-PREFIX="${VOLCA_PREFIX:-$HOME/.local}"
-SHARE_DIR="$PREFIX/share/volca"
-BIN_DIR="$PREFIX/bin"
+BIN_DIR="$HOME/.local/bin"
 SHIM="$BIN_DIR/volca"
 
 VERSION="${1:-}"
@@ -67,6 +68,19 @@ case "$UNAME_S" in
 esac
 PLATFORM="${OS}-${ARCH}"
 
+# --- Resolve install root ----------------------------------------------------
+# Mirrors platformdirs.user_data_dir("volca", appauthor=False) — the same root
+# pyvolca.download() and install.ps1 use, so all three installers share it.
+
+if [ -n "${VOLCA_HOME:-}" ]; then
+    SHARE_DIR="$VOLCA_HOME"
+else
+    case "$OS" in
+        linux) SHARE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/volca" ;;
+        macos) SHARE_DIR="$HOME/Library/Application Support/volca" ;;
+    esac
+fi
+
 # --- Tooling sanity ----------------------------------------------------------
 
 for tool in curl tar; do

pyvolca/README.md

@@ -20,7 +20,7 @@ Requires Python ≥ 3.10 and a running VoLCA engine. Use `Server` (below) to run
 Most users should start with one of these two modes:
 
 - **You already have access to a VoLCA server** (for example a hosted server prepared by someone else): use `Client` only. You do not need `volca.toml`, and you do not need to install the VoLCA server locally.
-- **You want Python to start a local VoLCA engine process for you**: use `download()` once to fetch the VoLCA engine binary and reference data into pyvolca's cache, then use `Server` to start it from Python. `volca.toml` is still a normal file path passed to `Server(config=...)`; put it in your project directory, or pass an absolute path. Do not put it inside your virtualenv or inside `site-packages`.
+- **You want Python to start a local VoLCA engine process for you**: use `download()` once to fetch the VoLCA engine binary and reference data into the shared volca install dir (see [Where artefacts are installed](#where-artefacts-are-installed)), then use `Server` to start it from Python. `volca.toml` is still a normal file path passed to `Server(config=...)`; put it in your project directory, or pass an absolute path. Do not put it inside your virtualenv or inside `site-packages`.
 
 For a hosted server, the minimal connection looks like this:
 
@@ -50,7 +50,21 @@ with Server(config="./volca.toml", binary=str(installed.binary)) as srv:
     print(c.list_databases())
 ```
 
-In this local mode, `download()` stores the engine binary and reference data in pyvolca's user cache. `Server(config="./volca.toml")` still means “read `./volca.toml` relative to the current working directory”.
+In this local mode, `download()` stores the engine binary and reference data in the shared volca install dir (see below). `Server(config="./volca.toml")` still means “read `./volca.toml` relative to the current working directory”.
+
+### Where artefacts are installed
+
+`download()` writes to the same OS-native location as the `install.sh` / `install.ps1` shell installers, so any of the three tools populate the same directory:
+
+| Platform | Default install root |
+|---|---|
+| Linux   | `${XDG_DATA_HOME:-~/.local/share}/volca/` |
+| macOS   | `~/Library/Application Support/volca/` |
+| Windows | `%LOCALAPPDATA%\volca\` |
+
+Override with `VOLCA_HOME=/full/path` (full path; skips OS detection).
+
+If you ran `install.sh` or `install.ps1` first, `Server()` finds the installed engine without an extra `download()` call. If you previously used `pyvolca < 0.4` it cached artefacts under `<user_cache_dir>/pyvolca/` (Linux: `~/.cache/pyvolca/`); that directory is no longer read and can be removed (`rm -rf ~/.cache/pyvolca`).
 
 ## Local managed-server quick start
 
@@ -285,7 +299,6 @@ Pyvolca dispatches dynamically against the engine's OpenAPI spec, so it ships wi
 ## API reference
 
 <!-- BEGIN: api-reference -->
-
 _This reference is generated from the installed package. Run `python scripts/gen_api_md.py` to regenerate._
 
 ## Classes
@@ -476,7 +489,7 @@ An exchange with the environment (resource extraction or emission).
 
 Filter a supply-chain/consumers query by a classification (system, value, mode).
 
-Matches one classification system entry (e.g. ("Category", "Agricultural\\Food",
+Matches one classification system entry (e.g. ("Category", "Agricultural\Food",
 "exact")). Mode is "exact" (case-insensitive equality) or "contains" (substring).
 Multiple filters are AND-combined by the server.
 
@@ -725,13 +738,13 @@ common case for "what does this variant consume differently?". Pass
 
 Download the volca binary + data bundle for the current platform.
 
-Idempotent: if both artefacts are already extracted under the expected
-cache paths and ``force=False``, returns immediately without network.
+Idempotent: if both artefacts are already extracted under the install
+root and ``force=False``, returns immediately without network.
 
 Args:
     version: GH Release tag (``v0.7.0``); ``None`` resolves the latest.
     repo: GitHub repo slug. Default ``ccomb/volca``.
-    force: Re-download even if the cache looks complete.
+    force: Re-download even if the install root looks complete.
 
 Returns:
     :class:`Installed` with the resolved paths and versions.
@@ -742,6 +755,7 @@ Returns:
 
 Type alias: `Union[TechnosphereExchange, BiosphereExchange]`.
 
+
 <!-- END: api-reference -->
 
 ## See also