Refresh database helper documentation and automate the website

.githooks/fiskwise-version.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fiskwise contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.githooks/pre-commit

@@ -0,0 +1,98 @@
+#!/bin/sh
+# Fiskwise ecosystem version policy (canonical source: DeepWaterIMR/fiskwise).
+# See docs/VERSIONING.md and .githooks/fiskwise-version.LICENSE.
+# Ordinary commits increment patch once. Only a user-requested change may set
+# FISKWISE_VERSION_BUMP=minor or major. No R/Python runtime is required.
+set -eu
+repo_root=$(git rev-parse --show-toplevel)
+cd "$repo_root"
+git_dir=$(git rev-parse --git-dir)
+if [ -e "$git_dir/MERGE_HEAD" ] || [ -e "$git_dir/rebase-merge" ] || [ -e "$git_dir/rebase-apply" ]; then
+  exit 0
+fi
+if [ -f DESCRIPTION ]; then
+  metadata=DESCRIPTION
+  version_key=Version
+  date_key=Date
+elif [ -f VERSION ]; then
+  metadata=VERSION
+  version_key=version
+  date_key=date
+else
+  echo 'Fiskwise: no VERSION or DESCRIPTION; initialize the package version first.' >&2
+  exit 1
+fi
+# DESCRIPTION can contain scientific/package changes. Never stage unrelated edits.
+if ! git diff --quiet -- "$metadata"; then
+  echo "Fiskwise: stage intended $metadata changes before committing; unstaged metadata was preserved." >&2
+  exit 1
+fi
+read_version() {
+  sed -n "s/^$version_key:[[:space:]]*//p" | sed 's/[[:space:]]*$//' | head -n 1
+}
+file_version=$(read_version < "$metadata")
+head_version=$(git show "HEAD:$metadata" 2>/dev/null | read_version || true)
+valid_version() {
+  printf '%s\n' "$1" | grep -Eq '^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+}
+if ! valid_version "$file_version"; then
+  echo "Fiskwise: $metadata needs a three-part x.y.z version; no files changed." >&2
+  exit 1
+fi
+bump=${FISKWISE_VERSION_BUMP:-patch}
+case "$bump" in patch|minor|major) ;; *) echo 'Fiskwise: FISKWISE_VERSION_BUMP must be patch, minor or major.' >&2; exit 1 ;; esac
+if [ -z "$head_version" ]; then
+  # The first versioned commit adopts the declared initial version.
+  new_version=$file_version
+else
+  if ! valid_version "$head_version"; then
+    echo 'Fiskwise: HEAD has a non-standard version; review migration before committing.' >&2
+    exit 1
+  fi
+  major=${head_version%%.*}
+  rest=${head_version#*.}
+  minor=${rest%%.*}
+  patch=${rest#*.}
+  case "$bump" in
+    patch) new_version="$major.$minor.$((patch + 1))" ;;
+    minor) new_version="$major.$((minor + 1)).0" ;;
+    major) new_version="$((major + 1)).0.0" ;;
+  esac
+  # Allow a pre-staged expected bump, but never silently accept another version.
+  if [ "$file_version" != "$head_version" ] && [ "$file_version" != "$new_version" ]; then
+    echo "Fiskwise: expected $new_version; minor/major changes require an explicit user request and FISKWISE_VERSION_BUMP=minor|major." >&2
+    exit 1
+  fi
+fi
+today=$(date +%Y-%m-%d)
+has_date=$(grep -c "^$date_key:" "$metadata" || true)
+tmp="$metadata.fiskwise-tmp.$$"
+readme_tmp="README.md.fiskwise-tmp.$$"
+trap 'rm -f "$tmp" "$readme_tmp"' EXIT HUP INT TERM
+# Preserve DCF fields, UTF-8, and the original LF/CRLF convention.
+awk -v vk="$version_key" -v dk="$date_key" -v ver="$new_version" -v day="$today" -v existing_date="$has_date" '
+  NR == 1 { ending = ($0 ~ /\r$/ ? "\r" : "") }
+  { line = $0; sub(/\r$/, "", line)
+    if (line ~ "^" vk ":") line = vk ": " ver
+    if (line ~ "^" dk ":") { line = dk ": " day; has_date = 1 }
+    printf "%s%s\n", line, ending
+    if (line ~ "^" vk ":" && existing_date == 0) printf "%s: %s%s\n", dk, day, ending
+  }
+' "$metadata" > "$tmp"
+if ! cmp -s "$tmp" "$metadata"; then cat "$tmp" > "$metadata"; fi
+git add -- "$metadata"
+# Preserve unstaged README changes. The marker is optional (R packages use DESCRIPTION).
+if [ -f README.md ] && git diff --quiet -- README.md; then
+  awk -v ver="$new_version" -v day="$today" '
+    NR == 1 { ending = ($0 ~ /\r$/ ? "\r" : "") }
+    { line = $0; sub(/\r$/, "", line)
+      if (stamp) { line = "**Version " ver "** (" day ")"; stamp = 0 }
+      else if (line == "<!-- version -->") stamp = 1
+      printf "%s%s\n", line, ending
+    }
+  ' README.md > "$readme_tmp"
+  if ! cmp -s "$readme_tmp" README.md; then
+    cat "$readme_tmp" > README.md
+    git add -- README.md
+  fi
+fi

.github/workflows/pkgdown.yaml

@@ -0,0 +1,68 @@
+name: pkgdown
+
+on:
+  push:
+    branches: [master]
+    paths-ignore:
+      - docs/**
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pkgdown-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-pandoc@v2
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+      - name: Build site
+        # Runnable examples use local metadata/path helpers only. Network-using
+        # Biotic download and reference-data functions have no runnable examples.
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: pkgdown-site
+          path: docs
+          if-no-files-found: error
+          retention-days: 1
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: master
+      - name: Download site artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: pkgdown-site
+          path: site
+      - name: Deploy to existing Pages folder
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
+        with:
+          branch: master
+          folder: site
+          target-folder: docs
+          clean: true

AGENTS.md

@@ -85,3 +85,11 @@ ageall  <- dplyr::tbl(con, "ageall")   # age readings (lazy)
 mission <- dplyr::tbl(con, "mission")  # cruise/mission metadata (lazy)
 taxaindex <- dplyr::tbl(con, "taxaindex") # taxa reference data (lazy)
 ```
+
+
+## Versioning
+
+Every ordinary commit increments the patch version by 0.0.1 and stamps the current date in
+`DESCRIPTION`. The shared `.githooks/pre-commit` enforces this rule; enable it with
+`git config core.hooksPath .githooks`. Add a matching heading and summary to `NEWS.md` in the
+same commit. Minor or major version changes require an explicit maintainer request.

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: BioticExplorerServer
 Type: Package
 Title: R Package for Downloading Server-Side Data for BioticExplorer
-Version: 0.8.9
-Date: 2026-09-07
+Version: 0.8.11
+Date: 2026-10-25
 Authors@R: c(person("Mikko", "Vihtakari", email = "mikko.vihtakari@hi.no",
                   role = c("aut", "cre")), 
           person("Ibrahim", "Umar",
@@ -17,6 +17,7 @@ Description: This package can be used to download the IMR Biotic database and
         Institute's Biotic data from R.
 Depends: R (>= 3.5)
 Imports: data.table, DBI, RstoxData, dbplyr, duckdb, dplyr, httr2, sf, xml2
+Remotes: StoXProject/RstoxData
 Suggests: testthat (>= 3.0.0), withr
 Config/testthat/edition: 3
 URL: https://deepwaterimr.github.io/BioticExplorerServer

NEWS.md

@@ -1,3 +1,11 @@
+# BioticExplorerServer 0.8.11
+
+* Declare the upstream GitHub source for RstoxData so clean installations and CI can resolve the dependency.
+
+# BioticExplorerServer 0.8.10
+
+2026-10-25 Add automated pkgdown builds and Pages deployment. The site build uses local documentation examples and does not call the Biotic or reference APIs.
+
 # BioticExplorerServer 0.8.9
 
 *2026-10-14*

_pkgdown.yml

@@ -28,6 +28,15 @@ reference:
   - indexDatabase
   - repairDatabaseEncoding
 
+- title: Database path helpers
+  desc: >
+    Resolve default database locations and locate an existing local database.
+    These helpers only inspect local paths; they do not contact the IMR APIs.
+  contents:
+  - defaultDbPath
+  - dbPathCandidates
+  - findDatabase
+
 - title: Biotic data processing
   desc: >
     Functions to parse a single NMD Biotic XML file into R data tables.