feat(annotator): add nexuslims_annotate app for dataset annotation (#16)

  feat(annotator): add full NexusLIMS annotator app with branding updates

  ## nexuslims_annotate app

  Adds a new `nexuslims_annotate` Django app that allows authorized users
  to annotate and manage experiment records directly from the CDCS interface.

  Key capabilities:
  - Full-page annotator view: card-based layout of all datasets within a
    record, with drag-and-drop reordering via SortableJS
  - Shift-click range selection for checkboxes, with multi-card drag
    (dragging a selected card moves all selected cards together, with
    stacked shadow and "N selected" badge on the dragged element)
  - Inline editing of record fields via Monaco editor
  - Dataset move/reassignment between records and download dropdown
  - Annotator side panel (offcanvas) accessible from detail pages
  - Guided tour using Shepherd.js + Floating UI
  - Permission-gated: requires write permission; toggled via
    NX_ENABLE_ANNOTATOR setting; 404s if app not in INSTALLED_APPS
  - Robust input validation: rejects negative datasetIndex, guards against
    non-list moves JSON, XSS-safe, proper 404 handling
  - Full unit test suite with GitHub Actions CI workflow

  ## Branding

  - Replace favicon.png and detail-page loading spinner with the new
    NexusLIMS diffraction-pattern icon (icon.png / icon.svg)
  - Loading spinner is an inline SVG with two counter-rotating hexagonal
    rings of circles, animated via CSS keyframes (nx-cw / nx-ccw)
  - XSLT uses xsl:attribute for viewBox to preserve case under HTML
    serialization

  ## Terms of Use

  - Add setup_terms_of_use() to init_environment.py (Step 6): inserts a
    default Terms of Use page into the WebPage model on first run,
    idempotent on subsequent runs
  - Template override for the CDCS terms-of-use page with scoped CSS:
    centered 720px column, compact heading/paragraph spacing, lead style
    for first paragraph
  - Document customization path in CUSTOMIZATION.md

Author: jat255

.github/workflows/tests.yml

@@ -0,0 +1,28 @@
+name: Tests
+
+on:
+  push:
+    branches: ["main", "feat/**"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run python runtests.py

CLAUDE.md

@@ -154,8 +154,7 @@ dev-up           # Start services
 **For local development (outside Docker):**
 ```bash
 # Install/sync dependencies locally
-# IMPORTANT: Use --no-install-project flag (this is a Django app, not a package)
-uv sync --no-install-project --extra core --extra server
+uv sync
 
 # Or use the convenience alias from deployment directory
 cd deployment
@@ -241,13 +240,11 @@ The Dockerfile uses native UV commands for optimal performance:
 COPY pyproject.toml uv.lock ./
 
 # Install from lockfile (no dependency resolution needed - fast!)
-RUN uv sync --frozen --no-dev --extra core --extra server
+RUN uv sync --frozen
 ```
 
 **Flags explained:**
 - `--frozen`: Use exact versions from lockfile (fail if lockfile is outdated)
-- `--no-dev`: Skip development dependencies (not needed in Docker)
-- `--extra core --extra server`: Install optional dependency groups
 
 ### Why UV?
 
@@ -257,6 +254,34 @@ RUN uv sync --frozen --no-dev --extra core --extra server
 - **Reliable**: Better conflict resolution than pip
 - **Efficient**: Shared cache across projects, parallel downloads
 
+## Running Tests
+
+Tests use `runtests.py` at the repo root, which runs Django tests with an in-memory SQLite database (no Docker or external services required).
+
+### Running Tests Locally
+
+```bash
+# From the repo root, with uv:
+uv run python runtests.py
+
+# Or with a local venv:
+python runtests.py
+```
+
+### How It Works
+
+- Uses `tests/test_settings.py` as the Django settings module
+- Runs `migrate` automatically before tests (in-memory SQLite)
+- Discovers and runs all tests in the `tests/` directory
+- Exits with a non-zero code if any tests fail
+
+### Test Settings (`tests/test_settings.py`)
+
+- Uses an in-memory SQLite database (`:memory:`) - no external DB needed
+- Loads `.env` via `python-dotenv` if present
+- `INSTALLED_APPS` includes `nexuslims_annotate` and `tests`
+- `ROOT_URLCONF` points to `tests.urls`
+
 ## Planning Documents
 
 All planning and analysis documents should be stored in this repository, not in the user's home directory:

deployment/Dockerfile

@@ -16,10 +16,7 @@ COPY pyproject.toml uv.lock README.md ./
 # Install all dependencies using UV sync
 # UV_PROJECT_ENVIRONMENT: Install to system Python instead of creating venv
 # --frozen: Use exact versions from uv.lock (reproducible builds)
-# --no-dev: Skip dev dependencies (not needed in Docker)
-# --no-install-project: Skip installing the project itself (just dependencies)
-# --extra: Install optional dependency groups
-RUN UV_PROJECT_ENVIRONMENT=/usr/local uv sync --frozen --no-dev --no-install-project --extra core --extra server
+RUN UV_PROJECT_ENVIRONMENT=/usr/local uv sync --frozen
 
 # Copy application source code and configuration
 COPY manage.py ./

deployment/dev-commands.ps1

@@ -138,7 +138,7 @@ function dev-uv-upgrade {
 
 function dev-uv-sync {
     Push-Location ..
-    uv sync --no-install-project --extra core --extra server
+    uv sync
     Pop-Location
 }
 

deployment/dev-commands.sh

@@ -57,7 +57,7 @@ alias dev-update-xslt-list='bash scripts/update-xslt.sh list'
 # Note: --no-install-project skips building the project itself (Django app, not a package)
 alias dev-uv-lock='cd .. && uv lock && cd deployment'
 alias dev-uv-upgrade='cd .. && uv lock --upgrade && cd deployment'
-alias dev-uv-sync='cd .. && uv sync --no-install-project --extra core --extra server && cd deployment'
+alias dev-uv-sync='cd .. && uv sync && cd deployment'
 alias dev-uv-add='echo "Usage: cd .. && uv add package-name && cd deployment && dev-build-clean"'
 
 echo "NexusLIMS-CDCS Development aliases loaded! Available commands:"

deployment/scripts/init_environment.py

@@ -645,6 +645,105 @@ def setup_api_tokens(superuser):
     log_success(f"Created {token_name} API token for user '{superuser.username}'")
 
 
+def setup_terms_of_use():
+    """Insert a default Terms of Use page if none exists.
+
+    The content is stored as a WebPage record in the database and can be
+    updated at any time through the admin UI at:
+        /admin/core-admin/core_website_app_terms
+    """
+    log_info("Checking Terms of Use page...")
+
+    try:
+        from core_main_app.components.web_page.models import WebPage
+        from core_website_app.commons.enums import WEB_PAGE_TYPES
+
+        t = WEB_PAGE_TYPES["terms_of_use"]
+
+        # If any non-empty record exists, leave it alone so admins can customise freely
+        pages = WebPage.objects.filter(type=t)
+        if pages.filter(content__regex=r'\S').exists():
+            log_success("Terms of Use page already exists")
+            return
+
+        # Clean up any empty/blank records before inserting
+        pages.delete()
+
+    except Exception:
+        pass  # No record yet -- fall through to create one
+
+    default_content = """
+<p>
+  These Terms of Use govern your access to and use of this NexusLIMS instance.
+  By accessing this site you agree to the terms below. The system administrator
+  may update these terms at any time; continued use of the system after changes
+  are posted constitutes acceptance of the revised terms.
+</p>
+
+<h5>1. Authorised Use</h5>
+<p>Access to this system is granted solely for legitimate scientific research,
+data management, and analysis activities consistent with the mission of the
+operating institution. You must not use the system for any unlawful purpose
+or in any way that disrupts the availability of the service for other users.</p>
+
+<h5>2. User Accounts</h5>
+<p>You are responsible for maintaining the confidentiality of your login
+credentials and for all activity that occurs under your account. Notify the
+system administrator immediately if you suspect unauthorised access.
+Accounts that have been inactive for an extended period may be suspended
+at the discretion of the administrator.</p>
+
+<h5>3. Data and Intellectual Property</h5>
+<p>You retain ownership of any data you upload. By uploading data you grant
+the system the right to store, process, and display that data as necessary
+to provide the service. You are responsible for ensuring that you have the
+right to upload and share any data you submit, and that doing so does not
+violate applicable laws or third-party agreements.</p>
+
+<h5>4. Acceptable Data Standards</h5>
+<p>Uploaded records should conform to the NexusLIMS schema and represent
+genuine experimental data. Falsification, fabrication, or misrepresentation
+of research data is a serious violation and may result in account suspension
+and referral to institutional authorities.</p>
+
+<h5>5. Privacy</h5>
+<p>This system may collect information about your usage (such as login times
+and records accessed) for administrative and audit purposes. This information
+is not shared with third parties except as required by law or institutional
+policy.</p>
+
+<h5>6. Disclaimer of Warranties</h5>
+<p>This system is provided &ldquo;as is&rdquo; without warranty of any kind. The operating
+institution makes no guarantees regarding uptime, data integrity, or fitness
+for a particular purpose. Users are encouraged to maintain independent
+backups of critical data.</p>
+
+<h5>7. Limitation of Liability</h5>
+<p>To the fullest extent permitted by applicable law, the operating institution
+shall not be liable for any indirect, incidental, or consequential damages
+arising from your use of or inability to use this system.</p>
+
+<h5>8. Contact</h5>
+<p>Questions about these terms or your account should be directed to the
+system administrator via the <a href="/contact/">contact page</a>.</p>
+"""
+
+    try:
+        from core_main_app.components.web_page.models import WebPage
+        from core_website_app.commons.enums import WEB_PAGE_TYPES
+        from core_website_app.components.terms_of_use import api as terms_api
+
+        page = WebPage()
+        page.type = WEB_PAGE_TYPES["terms_of_use"]
+        page.content = default_content.strip()
+        terms_api.upsert(page)
+        log_success("Default Terms of Use page created")
+        log_info("  Update it any time at: /admin/core-admin/core_website_app_terms")
+
+    except Exception as e:
+        log_error(f"Failed to create Terms of Use page: {e}")
+
+
 def load_exporters():
     """Load the exporters into the database."""
     log_info("Loading exporters...")
@@ -756,6 +855,9 @@ def main():
         # Step 5: Load exporters
         load_exporters()
 
+        # Step 6: Set up default Terms of Use page
+        setup_terms_of_use()
+
         print("=" * 70)
         log_success("Initialization complete!")
 

deployment/test-data/nexuslims-test-data.tar.gz

@@ -105,6 +105,7 @@
 
     # NexusLIMS customizations (must come before core apps)
     'nexuslims_overrides',
+    'nexuslims_annotate',
 
     # Core apps
     "core_main_app",

mdcs/settings.py

@@ -13,6 +13,7 @@
     1. Add a URL to urlpatterns:  re_path(r'^blog/', include('blog.urls'))
 """
 
+from django.conf import settings
 from django.conf.urls import include
 from django.contrib import admin
 from django.urls import re_path
@@ -30,6 +31,12 @@
     ),
     # NexusLIMS overrides MUST come before core_main_app to override its URLs
     re_path(r"^", include("nexuslims_overrides.urls")),
+    *(
+        [re_path(r"^annotate/", include("nexuslims_annotate.urls"))]
+        if "nexuslims_annotate" in settings.INSTALLED_APPS
+        and getattr(settings, "NX_ENABLE_ANNOTATOR", True)
+        else []
+    ),
     re_path(r"^", include("core_main_app.urls")),
     re_path(r"^home/", include("mdcs_home.urls")),
     re_path(r"^", include("core_website_app.urls")),