Breaking/hotfix 1

.clj-kondo/config.edn

@@ -1,8 +1,47 @@
-{:output {:exclude-files [".*resources/public/js/compiled.*"
+{;; Prevent analysis of compiled CLJS output -- source copies live there
+ ;; and cause "redefined var" when IDE analyzes both src/ and compiled/.
+ :exclude-files "resources/public/js/compiled"
+ :output {:exclude-files [".*resources/public/js/compiled.*"
                           ".*docker/scripts/.*"]}
- :linters {:shadowed-fn-param {:level :off}
-           :shadowed-var {:level :off}
+ :linters {;; Enabled at :warning so NEW accidental shadows are caught.
+           ;; :exclude covers established patterns: core vars used as param names
+           ;; (name, key, type, etc.) and domain terms used as both defs and params
+           ;; (level, ability, armor, etc.) across modifier/option/character code.
+           :shadowed-fn-param {:level :warning
+                               :exclude [source character]}
+           :shadowed-var {:level :warning
+                          :exclude [;; clojure.core / cljs.core vars used as parameter names
+                                    name key type val num first last next ns fn comp
+                                    int char chars bytes str time atom ref set class
+                                    list map range min max mod count filter flatten
+                                    keys vals identity ancestors comparator cond
+                                    list? sequential? set?
+                                    ;; re-frame.core/path — used as param in route handlers
+                                    path
+                                    ;; Domain terms used as both ns-level defs and fn params
+                                    ;; in modifiers.cljc, options.cljc, character.cljc, etc.
+                                    level levels level-key ability abilities armor weapon weapons
+                                    action alignment cls equipment size subclass-name
+                                    skill-options skill-expertise tool-options weapon-proficiency-options
+                                    spellcasting-template feat-selections cantrip-selections
+                                    sorted-items selected-plugin-options built-template
+                                    ;; One-off project-var shadows — established code patterns
+                                    ;; where a fn/let binding intentionally shadows its ns def
+                                    actual-path all-armor-inventory app-header
+                                    available-selections builder-page character-summary
+                                    children critical-hit-values custom-equipment entity
+                                    first-class? following-usernames i instant item-adder
+                                    languages levels-selection message mod-cfg mod-key
+                                    name-result parties party-owner prepared-spells-by-class
+                                    prepares-spells query-map search-results source speed
+                                    spells-known style view]}
+           ;; 213 warnings. Many namespaces are required purely for side effects:
+           ;; re-frame event/sub registrations, modifier macros, spec loading.
+           ;; Remaining are test cleanup debt (genuinely unused test requires).
            :unused-namespace {:level :off}
+           ;; 567 warnings. Destructured map bindings used for documentation or
+           ;; structure (e.g. {:keys [name level key]} where only some are used
+           ;; in the body). Renaming to _ would lose semantic readability.
            :unused-binding {:level :off}
            :missing-else-branch {:level :warning}
            :clojure-lsp/unused-public-var
@@ -14,17 +53,17 @@
                       orcpub.dnd.e5.options/spell-tags
                       orcpub.dnd.e5.options/potent-spellcasting
                       ;; Live callers exist but LSP can't trace them
-                      orcpub.common/dissoc-in                ; events.cljs
+                      orcpub.common/dissoc-in                ; events.cljs:2976
                       orcpub.dnd.e5.character/add-ability-namespaces ; test
                       ;; Cross-file refs: used in template.cljc but defined in spell_subs.cljs
                       orcpub.dnd.e5.spell-subs/sunlight-sensitivity
                       orcpub.dnd.e5.spell-subs/mask-of-the-wild-mod]
             ;; re-frame event handlers are dispatched via keyword, not var reference.
             ;; LSP can't connect reg-event-db registration to (dispatch [:keyword]).
             :exclude-when-defined-by #{re-frame.core/reg-event-db
-                                        re-frame.core/reg-event-fx
-                                        re-frame.core/reg-sub
-                                        re-frame.core/reg-sub-raw}}
+                                       re-frame.core/reg-event-fx
+                                       re-frame.core/reg-sub
+                                       re-frame.core/reg-sub-raw}}
            ;; garden.selectors vars are generated by macros (defselector,
            ;; defpseudoclass, gen-pseudo-class-defs, etc.) at compile time.
            ;; clj-kondo can't resolve macro-generated vars statically and
@@ -34,8 +73,9 @@
                       ;; errors.cljc macros behind #?(:clj) reader conditional —
                       ;; one kondo instance can't resolve them
                       orcpub.errors]}
-           ;; read-string is a valid cljs.core symbol that clj-kondo
-           ;; doesn't recognize in its ClojureScript analysis data.
+           ;; Macros that introduce bindings kondo can't resolve statically.
+           ;; Each (ns/macro) entry suppresses unresolved symbols inside that
+           ;; macro's body. Modifier macros use defmacro with gensym bindings.
            :unresolved-symbol
            {:exclude
             [read-string
@@ -66,7 +106,16 @@
              (orcpub.entity-spec/make-entity)
              (orcpub.routes-test/with-conn)
              (orcpub.routes.folder-test/with-conn)
+             (orcpub.email-change-test/with-conn)
              (user/with-db)]}}
+ ;; native/cljs and web/cljs are separate source roots; kondo doesn't know
+ ;; about them so ns names appear to mismatch their file paths.
+ :config-in-ns {orcpub.core {:linters {:namespace-name-mismatch {:level :off}}}
+                orcpub.views {:linters {:namespace-name-mismatch {:level :off}}}
+                orcpub.dnd.e5.native-views {:linters {:namespace-name-mismatch {:level :off}}}}
+ ;; with-conn macros use bare symbol bindings — handled via
+ ;; :unresolved-symbol :exclude above (macroexpand hooks can't find
+ ;; the test namespaces and produce noisy warnings).
  :lint-as {reagent.core/with-let clojure.core/let
            hiccup.def/defhtml clojure.core/defn
            user/with-db clojure.core/let

.devcontainer/Dockerfile

@@ -0,0 +1,30 @@
+FROM clojure:temurin-21-lein
+
+# Install useful dev tools (including unzip for Datomic Pro)
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends rlwrap git curl tmux make git-lfs lsof iproute2 unzip rsync maven \
+    libfreetype6 fontconfig fonts-dejavu-core fonts-liberation libxrender1 libxext6 libxi6 libxrandr2 \
+ && rm -rf /var/lib/apt/lists/*
+
+# Ensure git-lfs is configured system-wide so LFS files are available in Codespaces
+RUN git lfs install --system || true
+
+# Install Leiningen so `lein` is available for LSP and project tasks
+RUN curl -fsSL https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein -o /usr/local/bin/lein \
+    && chmod +x /usr/local/bin/lein \
+    && /usr/local/bin/lein --version || true
+
+WORKDIR /workspace
+
+# Copy project source (lib/ includes pdfbox vendor deps from host)
+COPY . /workspace
+
+# Pre-cache Datomic Pro zip so post-create.sh skips the download.
+# The actual install (extract, flatten, maven-install) is done by post-create.sh
+# because the volume mount overwrites /workspace during container creation.
+ARG DATOMIC_VERSION=1.0.7482
+RUN curl --fail -L -o "/tmp/datomic-pro-${DATOMIC_VERSION}.zip" \
+      "https://datomic-pro-downloads.s3.amazonaws.com/${DATOMIC_VERSION}/datomic-pro-${DATOMIC_VERSION}.zip"
+
+# Default shell to bash for VS Code terminal
+SHELL ["/bin/bash", "-c"]

.devcontainer/devcontainer.json

@@ -0,0 +1,45 @@
+{
+  "name": "ClojureScript Lein-Figwheel Dev",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/sshd:1": {
+      "version": "latest"
+    }
+  },
+  "forwardPorts": [8890, 3449, 4334],
+  "portsAttributes": {
+    "8890": {
+      "label": "Backend Server",
+      "onAutoForward": "notify"
+    },
+    "3449": {
+      "label": "Figwheel",
+      "onAutoForward": "silent"
+    },
+    "4334": {
+      "label": "Datomic",
+      "onAutoForward": "silent"
+    }
+  },
+  "postCreateCommand": [
+    "bash",
+    "./.devcontainer/post-create.sh"
+  ],
+  "containerEnv": {
+    "POST_CREATE_VERBOSE": "1",
+    "DATOMIC_VERSION": "1.0.7482",
+    "DATOMIC_URL": "datomic:dev://localhost:4334/orcpub"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "betterthantomorrow.calva",
+        "borkdude.clj-kondo"
+      ],
+      "settings": {}
+    }
+  }
+}

.devcontainer/post-create.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+#
+# Datomic Pro install script for devcontainer
+#
+# 1. Always remove lib/com/datomic/datomic-{type}/<version> if it exists
+# 2. Unzip the Datomic zip (from /lib or /tmp, download if missing) into target dir
+# 3. Flatten top-level subdir if present (some zips nest contents)
+# 4. Run vendor maven-install from bin/
+#
+# This script does NOT cherry-pick, rename, or check for specific files before extraction.
+# All contents of the zip are placed in the target directory, overwriting any previous install.
+#
+
+set -euo pipefail
+
+# Source .env from repo root if present (authoritative config)
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+if [ -f "$REPO_ROOT/.env" ]; then
+  set -a
+  # shellcheck disable=SC1090
+  . "$REPO_ROOT/.env"
+  set +a
+fi
+
+# Redirect all output to persistent logs for visibility during Codespace creation
+LOG="/tmp/orcpub-post-create.log"
+WORKSPACE_LOG="$REPO_ROOT/.devcontainer/post-create.log"
+# Ensure workspace log exists and is writable (best-effort)
+mkdir -p "$(dirname "$WORKSPACE_LOG")" 2>/dev/null || true
+touch "$WORKSPACE_LOG" 2>/dev/null || true
+# Tee to both /tmp and workspace log so it's inspectable in Codespaces UI
+exec > >(tee -a "$LOG" "$WORKSPACE_LOG") 2>&1
+
+# Optional verbose tracing: set POST_CREATE_VERBOSE=1 to enable `set -x`
+if [ "${POST_CREATE_VERBOSE:-0}" = "1" ]; then
+  echo "[POST-CREATE] Verbose tracing enabled"
+  set -x
+fi
+
+# Timestamp helper
+ts() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+log() { echo "$(ts) [POST-CREATE] $*"; }
+
+log "Starting postCreateCommand... (logging to $LOG and $WORKSPACE_LOG)"
+
+# Configuration with defaults
+DATOMIC_TYPE="${DATOMIC_TYPE:-pro}"
+RAW_DATOMIC_VERSION="${DATOMIC_VERSION:-1.0.7482}"
+# basename in case a path was provided (e.g., /tmp/datomic-pro-1.0.7482.zip)
+RAW_DATOMIC_VERSION="$(basename "$RAW_DATOMIC_VERSION")"
+# strip leading prefix and trailing .zip if present
+DATOMIC_VERSION="${RAW_DATOMIC_VERSION#datomic-${DATOMIC_TYPE}-}"
+DATOMIC_VERSION="${DATOMIC_VERSION%.zip}"
+
+log "Using DATOMIC_TYPE=$DATOMIC_TYPE, DATOMIC_VERSION=$DATOMIC_VERSION"
+
+# Paths
+TARGET_DIR="lib/com/datomic/datomic-${DATOMIC_TYPE}/${DATOMIC_VERSION}"
+ZIP_NAME="datomic-${DATOMIC_TYPE}-${DATOMIC_VERSION}.zip"
+DOWNLOAD_URL="https://datomic-pro-downloads.s3.amazonaws.com/${DATOMIC_VERSION}/${ZIP_NAME}"
+
+# Clean and prepare target directory
+if [ -d "${TARGET_DIR}" ]; then
+  log "Removing existing installation at ${TARGET_DIR}"
+  rm -rf "${TARGET_DIR}"
+fi
+mkdir -p "${TARGET_DIR}"
+
+# Find Datomic zip in /lib/ or /tmp/, download if missing
+ZIP_PATH="/lib/${ZIP_NAME}"
+if [ ! -f "$ZIP_PATH" ]; then
+  ZIP_PATH="/tmp/${ZIP_NAME}"
+  if [ ! -f "$ZIP_PATH" ]; then
+    log "Downloading Datomic from $DOWNLOAD_URL"
+    curl --fail --location --progress-bar -o "$ZIP_PATH" "$DOWNLOAD_URL"
+  fi
+fi
+
+# Verify zip integrity (handles corrupt/incomplete downloads)
+if ! unzip -t "$ZIP_PATH" >/dev/null 2>&1; then
+  log "Corrupt or incomplete zip detected, removing and re-downloading..."
+  rm -f "$ZIP_PATH"
+  curl --fail --location --progress-bar -o "$ZIP_PATH" "$DOWNLOAD_URL"
+
+  # Verify the re-download
+  if ! unzip -t "$ZIP_PATH" >/dev/null 2>&1; then
+    log "ERROR: Re-downloaded zip is still corrupt. Check network connection or URL."
+    log "URL: $DOWNLOAD_URL"
+    exit 1
+  fi
+fi
+
+# Unzip Datomic distribution into target dir
+log "Extracting $ZIP_PATH to $TARGET_DIR"
+unzip -q "$ZIP_PATH" -d "${TARGET_DIR}"
+
+# Flatten if needed (some zips nest contents in a subdirectory)
+TOP_SUBDIR=$(find "${TARGET_DIR}" -mindepth 1 -maxdepth 1 -type d -print -quit || true)
+if [ -n "${TOP_SUBDIR}" ] && [ -z "$(find "${TARGET_DIR}" -maxdepth 1 -type f -print -quit)" ]; then
+  log "Flattening nested directory structure"
+  mv "${TOP_SUBDIR}"/* "${TARGET_DIR}/"
+  rmdir "${TOP_SUBDIR}"
+fi
+
+# Run vendor maven-install
+if [ -x "${TARGET_DIR}/bin/maven-install" ]; then
+  log "Running maven-install..."
+  (cd "${TARGET_DIR}" && bash bin/maven-install)
+else
+  log "ERROR: bin/maven-install not found or not executable in ${TARGET_DIR}/bin"
+  exit 1
+fi
+
+log "Datomic ${DATOMIC_TYPE} ${DATOMIC_VERSION} installed successfully to ${TARGET_DIR}"

.dockerignore

@@ -3,9 +3,18 @@
 .cache
 .idea
 .github
+
+# Secrets — never copy into build context
+.env
+.lein-env
+logs/console.log
 docker-compose*
 test/*
 *.md
 data/*
 log/*
-backups/*
+backups/*
+backup/*
+
+# Datomic Pro distribution (~280MB) — Docker images download their own from S3
+lib/com/datomic/

.env.example

@@ -1,28 +1,70 @@
 # ============================================================================
-# Dungeon Master's Vault — Docker Environment Configuration
+# Dungeon Master's Vault — Environment Configuration
 #
 # Copy this file to .env and update the values:
 #   cp .env.example .env
 #
 # Or run the setup script to generate .env with secure random values:
 #   ./docker-setup.sh
+#
+# IMPORTANT: This file defaults to Docker Compose hostnames (e.g., "datomic").
+# For bare-metal installs (no Docker), see the "Bare-metal" comments below.
 # ============================================================================
 
 # --- Application ---
 PORT=8890
 
+# Upstream hostname for nginx proxy_pass (Docker service name or IP address).
+# Docker Compose: leave as default (resolves via Docker DNS).
+# Bare-metal proxy: set to 127.0.0.1 (or the host where the app is running).
+# ORCPUB_HOST=127.0.0.1
+
+# Image tag for docker-compose.yaml (pre-built images only, ignored by build compose)
+# ORCPUB_TAG=release-v2.5.0.27
+
 # --- Datomic Database ---
+# Datomic Pro with dev storage protocol (required for Java 21 support)
 # ADMIN_PASSWORD secures the Datomic admin interface
 # DATOMIC_PASSWORD is used by the application to connect to Datomic
 # The password in DATOMIC_URL must match DATOMIC_PASSWORD
 ADMIN_PASSWORD=change-me-admin
 DATOMIC_PASSWORD=change-me-datomic
-DATOMIC_URL=datomic:free://datomic:4334/orcpub?password=change-me-datomic
+# Docker Compose: use "datomic" (Docker service name, resolves via Docker DNS)
+# Bare-metal:     use "localhost" (transactor running on the same machine)
+DATOMIC_URL=datomic:dev://datomic:4334/orcpub?password=change-me-datomic
+# DATOMIC_URL=datomic:dev://localhost:4334/orcpub?password=change-me-datomic
+
+# --- Transactor Tuning ---
+# These rarely need changing. See docker/transactor.properties.template.
+# ALT_HOST: peer fallback hostname (default: 127.0.0.1, set to service name for Swarm)
+# ENCRYPT_CHANNEL: encrypt peer-transactor communication (default: true)
+ALT_HOST=127.0.0.1
+ENCRYPT_CHANNEL=true
+# Password rotation — set OLD vars during rotation, remove after all peers reconnect
+# ADMIN_PASSWORD_OLD=
+# DATOMIC_PASSWORD_OLD=
 
 # --- Security ---
-# Secret used to sign JWT tokens (20+ characters recommended)
+# REQUIRED: JWT signing secret. Authentication will fail without this.
+# 20+ random characters recommended (e.g., openssl rand -hex 16)
 SIGNATURE=change-me-to-something-unique-and-long
 
+# Content Security Policy (strict|permissive|none)
+CSP_POLICY=strict
+
+# Dev mode: CSP violations are logged (Report-Only) instead of blocked,
+# allowing Figwheel hot-reload scripts to execute.
+DEV_MODE=true
+
+# --- Plugins ---
+# URL to fetch server-hosted .orcbrew plugins on first page load.
+# Leave empty to disable (plugins come only from local file imports).
+# LOAD_HOMEBREW_URL=/homebrew.orcbrew
+
+# --- Logs ---
+# Defaults to project logs/ if unset
+LOG_DIR=
+
 # --- Email (SMTP) ---
 # Leave EMAIL_SERVER_URL empty to disable email functionality
 EMAIL_SERVER_URL=

.github/workflows/continuous-integration.yml

@@ -164,6 +164,7 @@ jobs:
 
       - name: Post PR comment with results
         if: github.event_name == 'pull_request' && always()
+        continue-on-error: true  # Fork PRs get read-only GITHUB_TOKEN
         uses: actions/github-script@v7
         with:
           script: |