Open Perpetuum wiki (static site, Zola)

.github/workflows/wiki.yml

@@ -0,0 +1,199 @@
+# Builds the Zola static site and deploys it to GitHub Pages.
+# Generated markdown is committed to git, so this build needs no database.
+
+name: Wiki
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+  security-events: write
+
+concurrency:
+  group: "wiki"
+  cancel-in-progress: true
+
+env:
+  ZOLA_VERSION: v0.23.6
+
+jobs:
+  ratchet:
+    name: Ratchet (action pins)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # ratchet:actions/checkout@v4
+
+      - name: Download ratchet (pinned release)
+        run: |
+          set -euo pipefail
+          curl -sSfL -o /tmp/ratchet.tar.gz \
+            "https://github.com/sethvargo/ratchet/releases/download/v0.12.0/ratchet_0.12.0_linux_amd64.tar.gz"
+          echo "0d14cb829d3f5068454402f8198b0d9a29b776c8a070ef3f7e7bbb4f53d16aa15309f8e5042cbb3330b2d415b3c058ef269be946cc267098e2e4ad8a75fa1b5c  /tmp/ratchet.tar.gz" | sha512sum -c -
+          tar xzC /tmp -f /tmp/ratchet.tar.gz
+
+      - name: Lint pins
+        run: /tmp/ratchet lint .github/workflows/wiki.yml
+
+      - name: Check pins match their tags
+        # Resolves the # ratchet: constraints and diffs against the committed
+        # file: fails when a pinned SHA no longer matches its tag (tag moved
+        # upstream or was re-pointed). Fix by running 'ratchet update' locally.
+        run: |
+          /tmp/ratchet update -out /tmp/wiki.updated.yml .github/workflows/wiki.yml
+          if ! diff -u .github/workflows/wiki.yml /tmp/wiki.updated.yml; then
+            echo "::error::Pinned action versions have drifted from their tags. Run 'ratchet update .github/workflows/wiki.yml' and commit the result."
+            exit 1
+          fi
+
+  sast-csharp:
+    name: SAST (CodeQL, C#)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # ratchet:actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@1190a975f95ce23525efb6a3fc21ea29567c1b52 # ratchet:github/codeql-action/init@v3
+        with:
+          languages: csharp
+          build-mode: manual
+          config-file: ./codeql-config.yml
+
+      - name: Build generator (.NET)
+        run: dotnet build generator/Perpetuum.WikiGenerate/Perpetuum.WikiGenerate.csproj -c Release
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@1190a975f95ce23525efb6a3fc21ea29567c1b52 # ratchet:github/codeql-action/analyze@v3
+
+  sast-js:
+    name: SAST (CodeQL, JS)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # ratchet:actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@1190a975f95ce23525efb6a3fc21ea29567c1b52 # ratchet:github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+          config-file: ./codeql-config.yml
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@1190a975f95ce23525efb6a3fc21ea29567c1b52 # ratchet:github/codeql-action/analyze@v3
+
+  test:
+    name: Tests (Playwright)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # ratchet:actions/checkout@v4
+
+      - name: Cache game layer data (zone map terrain)
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # ratchet:actions/cache@v4
+        with:
+          path: .assets
+          key: wiki-zone-layers-v1
+
+      - name: Fetch game layer data + generate zone map terrain
+        # The zone map PNGs are not committed; they are generated here from
+        # the game's layer data (fetched by tools/fetch_zone_layers.sh —
+        # Steam dedicated server + the public gamma Drive archive). Zones
+        # whose layers only ship in the game client keep their committed
+        # derived PNGs from static/zonemaps-fallback/ (handled by the tool).
+        run: |
+          if ! command -v 7z >/dev/null; then
+            sudo apt-get update && sudo apt-get install -y p7zip-full
+          fi
+          bash tools/fetch_zone_layers.sh .assets
+          OP_ASSETS_DIR="$PWD/.assets" python3 tools/gen_zone_teleport_maps.py
+
+      - name: Install Zola
+        # The runner is non-root, so extract to the workspace, not /usr/local.
+        run: |
+          mkdir -p "$GITHUB_WORKSPACE/tools"
+          curl -sSfL -o /tmp/zola.tar.gz "https://github.com/getzola/zola/releases/download/${ZOLA_VERSION}/zola-${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
+          tar xzC "$GITHUB_WORKSPACE/tools" -f /tmp/zola.tar.gz
+          export PATH="$GITHUB_WORKSPACE/tools:$PATH"
+          echo "$GITHUB_WORKSPACE/tools" >> "$GITHUB_PATH"
+          zola --version
+
+      - name: Build
+        run: zola build --force -o public
+
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # ratchet:actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install test dependencies
+        run: npm ci
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run tests
+        run: npm test
+
+  build:
+    name: Build (Zola)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # ratchet:actions/checkout@v4
+
+      - name: Cache game layer data (zone map terrain)
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # ratchet:actions/cache@v4
+        with:
+          path: .assets
+          key: wiki-zone-layers-v1
+
+      - name: Fetch game layer data + generate zone map terrain
+        run: |
+          if ! command -v 7z >/dev/null; then
+            sudo apt-get update && sudo apt-get install -y p7zip-full
+          fi
+          bash tools/fetch_zone_layers.sh .assets
+          OP_ASSETS_DIR="$PWD/.assets" python3 tools/gen_zone_teleport_maps.py
+
+      - name: Install Zola
+        # The runner is non-root, so extract to the workspace, not /usr/local.
+        run: |
+          mkdir -p "$GITHUB_WORKSPACE/tools"
+          curl -sSfL -o /tmp/zola.tar.gz "https://github.com/getzola/zola/releases/download/${ZOLA_VERSION}/zola-${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
+          tar xzC "$GITHUB_WORKSPACE/tools" -f /tmp/zola.tar.gz
+          # GITHUB_PATH applies from the next step on; export PATH for this step.
+          export PATH="$GITHUB_WORKSPACE/tools:$PATH"
+          echo "$GITHUB_WORKSPACE/tools" >> "$GITHUB_PATH"
+          zola --version
+
+      - name: Build
+        # Zola 0.23 builds from the current directory (no -d flag); the
+        # default working directory is the repo root where config.toml lives.
+        run: zola build --force -o public
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # ratchet:actions/upload-pages-artifact@v3
+        with:
+          path: ./public
+
+  deploy:
+    name: Deploy to GitHub Pages
+    # Deploys only from main (pull_request runs build-only, so PR checks
+    # never touch the Pages environment).
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # ratchet:actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,10 @@
+public/
+node_modules/
+test-results/
+playwright-report/
+memory.md
+generator/**/bin/
+generator/**/obj/
+tools/__pycache__/
+static/zonemaps/*/
+.assets/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "server"]
+	path = server
+	url = https://github.com/OpenPerpetuum/PerpetuumServer2.git

LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

Makefile

@@ -0,0 +1,95 @@
+# Open Perpetuum Wiki — build tooling.
+#
+#   make build     build the static site into public/ (Docker, pinned Zola image)
+#   make serve     local live-reload server on :8085 (Docker; override WIKI_PORT=NNNN)
+#   make test      build + run the Playwright browser tests (needs node +
+#                  npm install; CHROMIUM_PATH=... to skip the Playwright
+#                  Chromium download)
+#   make zonemaps  regenerate the zone teleport maps: real terrain from the
+#                  game's layer data (fetched when no local checkout exists)
+#                  + clickable teleports (pure-stdlib Python, no database)
+#   make generate  regenerate the generated content pages from the database
+#   make clean     remove the build output
+#
+# The site build (build/serve) never needs a database: the generated markdown is
+# committed to git. `make generate` is only needed when the database content
+# changes; it requires the .NET 8 SDK and a reachable game database.
+
+ZOLA_IMAGE := ghcr.io/getzola/zola:v0.23.6
+PYTHON_IMAGE := python:3.12-slim
+WIKI_PORT  ?= 8085
+
+# Generator inputs (make generate).
+#   WIKI_DB          SQL Server connection string (falls back to $PERPETUUM_CONNECTIONSTRING)
+#   WIKI_PLANTRULES  directory containing the plant rule files; defaults to the
+#                    server submodule (run `git submodule update --init server` first)
+WIKI_DB         ?= $(PERPETUUM_CONNECTIONSTRING)
+# ?= would not override an empty WIKI_PLANTRULES from the environment, so use ifdef.
+ifdef WIKI_PLANTRULES
+else
+WIKI_PLANTRULES = $(abspath server/src/Perpetuum.ServerService2/data/plantrules)
+endif
+DOTNET          ?= $(shell command -v dotnet 2>/dev/null || echo $(HOME)/.dotnet/dotnet)
+TTY_FLAG        := $(shell [ -t 0 ] && echo -it || echo -i)
+
+.PHONY: all build serve test zonemaps generate clean
+
+all: build
+
+# Post-process the generated zone teleport maps (static/zonemaps/*.svg):
+# REAL terrain backgrounds from the game's layer files, emphasized zone
+# border, and clickable teleport links. The game's layer data is NOT in
+# this repo; the tool reads it, in order of preference, from:
+#   1. a PerpetuumServer2 checkout (sibling ../PerpetuumServer2 or the
+#      server/ submodule) when one has custom-layers/ — full data
+#   2. .assets/ — fetched by tools/fetch_zone_layers.sh (Steam dedicated
+#      server + the public gamma Drive archive) when no checkout exists;
+#      zones only available in the game client then keep their committed
+#      derived PNGs from static/zonemaps-fallback/ (see the tool header)
+# Pure standard-library Python — no database, no pip installs.
+ASSETS ?= $(patsubst %/custom-layers,%,$(firstword $(wildcard ../PerpetuumServer2/custom-layers ./server/custom-layers .assets/custom-layers)))
+zonemaps:
+	ASSETS="$(ASSETS)"; if [ -z "$$ASSETS" ]; then bash tools/fetch_zone_layers.sh .assets; ASSETS=$$(pwd)/.assets; fi; OP_ASSETS_DIR="$$ASSETS" python3 tools/gen_zone_teleport_maps.py
+
+# Browser tests (tests/): mermaid syntax of every diagram + sidenav behaviour,
+# run against the built site. One-time setup: npm install.
+test: build
+	npm test
+
+# Build the static site with the pinned official Zola container (no local
+# install). The container runs as root (the image has no alpine coreutils),
+# so if a build is ever interrupted and leaves root-owned files in public/,
+# `make clean` removes them via a container.
+build:
+	docker run --rm \
+		-v "$$PWD:/src" \
+		$(ZOLA_IMAGE) -r /src build --force -o /src/public
+
+# Local live-reload server: http://localhost:$(WIKI_PORT)
+serve:
+	docker run --rm $(TTY_FLAG) \
+		-u "$$(id -u):$$(id -g)" \
+		-p "$(WIKI_PORT):1111" \
+		-v "$$PWD:/src" \
+		$(ZOLA_IMAGE) -r /src serve -i 0.0.0.0 --no-port-append -u "http://localhost:$(WIKI_PORT)/"
+
+# Regenerate the generated pages (content/content + zone index + zone map +
+# search index) from the database. See generator/README.md for the table
+# mapping. IMPORTANT: `make zonemaps` must run AFTER `make generate` —
+# generate rewrites the raw zone teleport SVGs, and zonemaps post-processes
+# them (terrain, markers, links); re-running generate afterwards overwrites
+# the post-processed maps with the raw output (the zone-map tests break).
+generate:
+	@test -n "$(WIKI_DB)" || { echo "error: set WIKI_DB (or PERPETUUM_CONNECTIONSTRING)"; exit 1; }
+	@test -d "$(WIKI_PLANTRULES)" || { echo "error: WIKI_PLANTRULES is not a directory: $(WIKI_PLANTRULES)"; \
+	  echo "hint: run 'git submodule update --init server' (or set WIKI_PLANTRULES to a GameRoot plantrules dir)"; exit 1; }
+	$(DOTNET) build -c Release generator/Perpetuum.WikiGenerate/Perpetuum.WikiGenerate.csproj
+	$(DOTNET) run -c Release --no-build --project generator/Perpetuum.WikiGenerate -- \
+		--connection "$(WIKI_DB)" \
+		--plantrules "$(WIKI_PLANTRULES)" \
+		--out content/content \
+		--zones-out content/zones
+
+clean:
+	rm -rf public 2>/dev/null || true
+	if [ -d public ]; then docker run --rm -v "$$PWD/public:/out" alpine:3.20 sh -c "rm -rf /out/*"; rm -rf public; fi