From 480ec37ef65fb173101714d99df29c0857a977ae Mon Sep 17 00:00:00 2001 From: Wally Hackenslacker Date: Mon, 23 Mar 2026 23:53:14 -0400 Subject: [PATCH] Updated AGENTS and CLAUDE files. --- AGENTS.md | 40 ++++++++++++++++++++++------------------ CLAUDE.md | 25 +++++++++++++++++-------- 2 files changed, 39 insertions(+), 26 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7f6c513..28e2f25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,13 +22,13 @@ This document is intentionally explicit so tasks can be completed with minimal r ## 3) Environment and Setup Commands -- Create venv: `python -m venv .venv` +- Create venv: `.venv/bin/python -m venv .venv` - Activate venv (bash): `source .venv/bin/activate` - Install deps: `pip install -r requirements.txt` -- Apply migrations: `python manage.py migrate` -- Run server: `python manage.py runserver` +- Apply migrations: `.venv/bin/python manage.py migrate` +- Run server: `.venv/bin/python manage.py runserver` -Local configuration is loaded from `.env` via `python-dotenv`. +Local configuration is loaded from `.env` via `.venv/bin/python-dotenv`. Use this minimum `.env` content for gallery paths: @@ -49,30 +49,30 @@ There is no dedicated linter or formatter config in-repo (no `ruff`, `flake8`, ` Use these commands as the standard validation set: -- Django system checks: `python manage.py check` -- Migration consistency check: `python manage.py makemigrations --check --dry-run` -- Python syntax sanity: `python -m compileall NibasaViewer viewer` -- Run Django tests (all): `python manage.py test` +- Django system checks: `.venv/bin/python manage.py check` +- Migration consistency check: `.venv/bin/python manage.py makemigrations --check --dry-run` +- Python syntax sanity: `.venv/bin/python -m compileall NibasaViewer viewer` +- Run Django tests (all): `.venv/bin/python manage.py test` Single-test execution patterns (important for fast iteration): -- Single test module: `python manage.py test viewer.test` -- Single test class: `python manage.py test viewer.test.GalleryViewTests` -- Single test method: `python manage.py test viewer.test.GalleryViewTests.test_search_action_url_uses_nested_path` +- Single test module: `.venv/bin/python manage.py test viewer.test` +- Single test class: `.venv/bin/python manage.py test viewer.test.GalleryViewTests` +- Single test method: `.venv/bin/python manage.py test viewer.test.GalleryViewTests.test_search_action_url_uses_nested_path` Notes: - If there are currently no tests, add focused tests near the changed behavior before large refactors. -- Prefer `python manage.py test ...` style labels over introducing a second test runner. +- Prefer `.venv/bin/python manage.py test ...` style labels over introducing a second test runner. ## 5) Operational Commands -- Pre-generate thumbnails: `python manage.py makethumbnails` +- Pre-generate thumbnails: `.venv/bin/python manage.py makethumbnails` - Create auth user (shell): - - `python manage.py shell` + - `.venv/bin/python manage.py shell` - `from django.contrib.auth.models import User` - `User.objects.create_user('', '', '')` -- Collect static files (deploy-time): `python manage.py collectstatic` +- Collect static files (deploy-time): `.venv/bin/python manage.py collectstatic` ## 6) Architecture and Change Boundaries @@ -90,6 +90,10 @@ Notes: - `_render_image` in `viewer/views.py` now exposes additional context keys used by the template and tests: `prev_url`, `next_url`, `prev_thumb`, `next_thumb`, `back_url`, `back_thumb`, `home_url`, `home_thumb`, and `image_meta` (dictionary with `filename`, `width`, `height`, `filesize`, `created`, `modified`). Agents modifying image-view behavior should update tests in `viewer/test.py` as well. - The top-bar sort button for the image view was replaced by an Info button (`fa-circle-info`) which shows a dropdown containing image metadata. The dropdown is vertically scrollable for long content. - The displayed main image now uses the same drop shadow and rounded corners as thumbnails (styles added to `viewer/static/css/styles.css`). + - The gallery view and image view were split into focused modules: `viewer/directory.py` handles directory browsing and search, `viewer/image.py` handles single-image rendering and metadata, `viewer/common.py` contains shared helpers (URL/query builders, sort helpers, breadcrumbs), and `viewer/utils.py` contains thumbnail helpers (`THUMB_SIZE`, `is_image_file`, `make_thumbnail`). `viewer/views.py` is now a thin delegating layer that routes requests to those modules. + - The image view (`viewer/image.py`) exposes richer context keys used by the template and tests: `prev_url`, `next_url`, `prev_thumb`, `next_thumb`, `back_url`, `back_thumb`, `home_url`, `home_thumb`, and `image_meta` (dictionary with `filename`, `width`, `height`, `filesize`, `created`, `modified`). Agents modifying image-view behavior should update tests in `viewer/test.py` as well. + - The top-bar sort button for the gallery view remains; the image view uses an Info button (`fa-circle-info`) which shows a dropdown containing image metadata. The dropdown is vertically scrollable for long content. + - Thumbnails are 128×128 (`THUMB_SIZE`) and generated lazily on-demand in `viewer/utils.py`; `IMAGE_EXTENSIONS` provides fast extension-based filtering. A management command `.venv/bin/python manage.py makethumbnails` exists for batch pre-generation. ## 7) Code Style Guidelines (Repository-Specific) @@ -169,8 +173,8 @@ When implementing a change, follow this minimum loop: Suggested pre-handoff command bundle: -- `python manage.py check` -- `python manage.py test` (or a targeted test label) -- `python -m compileall NibasaViewer viewer` +- `.venv/bin/python manage.py check` +- `.venv/bin/python manage.py test` (or a targeted test label) +- `.venv/bin/python -m compileall NibasaViewer viewer` This repository values stability, compatibility, and straightforward Django patterns over novelty. diff --git a/CLAUDE.md b/CLAUDE.md index aa0508a..07e7f2a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,6 +49,13 @@ The project has one Django app: **`viewer`**. All gallery functionality is conso - `utils.py` - Thumbnail generation helpers - `templates/` - Pure HTML templates (no JavaScript) - `static/` - CSS styling and navigation icons + - `views.py` - Thin delegating entry points that route to `viewer/directory.py` and `viewer/image.py` (see `gallery_view` in `viewer/views.py`). + - `directory.py` - Directory browsing, search, and list rendering helpers. + - `image.py` - Single-image rendering and metadata helpers. + - `common.py` - Shared helpers: URL/query builders, sorting, breadcrumbs, thumbnail utilities. + - `utils.py` - Thumbnail generation helpers. + - `templates/` - HTML templates (minimal JS via Bootstrap where needed). + - `static/` - CSS styling and navigation icons ### Gallery Data Flow @@ -76,21 +83,23 @@ Uses Django's built-in `django.contrib.auth` system: **`gallery_view()` function** (viewer/views.py:65-189) handles both: 1. **Directory browsing** when path points to folder: - - Lists subdirectories and images - - Supports search with recursive directory scanning (viewer/views.py:32-52) - - Paginates images at 28 per page (7 columns × 4 rows) - - Converts flat image lists to table rows for HTML rendering + - Lists subdirectories and images + - Supports search with recursive directory scanning (`viewer/directory.py:do_recursive_search`) + - Does not use server-side pagination; the gallery returns full image lists and templates render them in a grid + - Converts image lists to structured context used by templates 2. **Image viewing** when path points to file: - - Displays single image with prev/next navigation - - Finds sibling images in same directory - - Links to full-resolution image + - Displays single image with prev/next navigation + - Finds sibling images in same directory + - Links to full-resolution image + +The image view logic now lives in `viewer/image.py` and exposes additional context keys used by templates and tests (see `viewer/test.py`): `prev_url`, `next_url`, `prev_thumb`, `next_thumb`, `back_url`, `back_thumb`, `home_url`, `home_thumb`, and `image_meta` (filename/width/height/filesize/created/modified). ### Thumbnail Generation **Lazy generation approach** (viewer/utils.py): - Thumbnails created on-demand when viewing gallery -- 128×128 pixel size (hardcoded) + - 128×128 pixel size (`THUMB_SIZE`) and cached under `THUMBNAILS_ROOT` - Uses Pillow for image processing - Fast extension-based image detection (no MIME-type I/O)