WallyHackenslacker/NibasaViewer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated AGENTS and CLAUDE files.

Browse Source
This commit is contained in:
Wally Hackenslacker
2026-03-23 23:53:14 -04:00
parent 3e209519e5
commit 480ec37ef6
2 changed files with 39 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
AGENTS.md
View File

@@ -22,13 +22,13 @@ This document is intentionally explicit so tasks can be completed with minimal r
## 3) Environment and Setup Commands ## 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` - Activate venv (bash): `source .venv/bin/activate`
- Install deps: `pip install -r requirements.txt` - Install deps: `pip install -r requirements.txt`
- Apply migrations: `python manage.py migrate` - Apply migrations: `.venv/bin/python manage.py migrate`
- Run server: `python manage.py runserver` - 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: 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: Use these commands as the standard validation set:
- Django system checks: `python manage.py check` - Django system checks: `.venv/bin/python manage.py check`
- Migration consistency check: `python manage.py makemigrations --check --dry-run` - Migration consistency check: `.venv/bin/python manage.py makemigrations --check --dry-run`
- Python syntax sanity: `python -m compileall NibasaViewer viewer` - Python syntax sanity: `.venv/bin/python -m compileall NibasaViewer viewer`
- Run Django tests (all): `python manage.py test` - Run Django tests (all): `.venv/bin/python manage.py test`
Single-test execution patterns (important for fast iteration): Single-test execution patterns (important for fast iteration):
- Single test module: `python manage.py test viewer.test` - Single test module: `.venv/bin/python manage.py test viewer.test`
- Single test class: `python manage.py test viewer.test.GalleryViewTests` - Single test class: `.venv/bin/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 method: `.venv/bin/python manage.py test viewer.test.GalleryViewTests.test_search_action_url_uses_nested_path`
Notes: Notes:
- If there are currently no tests, add focused tests near the changed behavior before large refactors. - 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 ## 5) Operational Commands
- Pre-generate thumbnails: `python manage.py makethumbnails` - Pre-generate thumbnails: `.venv/bin/python manage.py makethumbnails`
- Create auth user (shell): - Create auth user (shell):
- `python manage.py shell` - `.venv/bin/python manage.py shell`
- `from django.contrib.auth.models import User` - `from django.contrib.auth.models import User`
- `User.objects.create_user('<USERNAME>', '<EMAIL>', '<PASSWORD>')` - `User.objects.create_user('<USERNAME>', '<EMAIL>', '<PASSWORD>')`
- 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 ## 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. - `_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 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 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) ## 7) Code Style Guidelines (Repository-Specific)
@@ -169,8 +173,8 @@ When implementing a change, follow this minimum loop:
Suggested pre-handoff command bundle: Suggested pre-handoff command bundle:
- `python manage.py check` - `.venv/bin/python manage.py check`
- `python manage.py test` (or a targeted test label) - `.venv/bin/python manage.py test` (or a targeted test label)
- `python -m compileall NibasaViewer viewer` - `.venv/bin/python -m compileall NibasaViewer viewer`
This repository values stability, compatibility, and straightforward Django patterns over novelty. This repository values stability, compatibility, and straightforward Django patterns over novelty.

25
CLAUDE.md
View File

@@ -49,6 +49,13 @@ The project has one Django app: **`viewer`**. All gallery functionality is conso
- `utils.py` - Thumbnail generation helpers - `utils.py` - Thumbnail generation helpers
- `templates/` - Pure HTML templates (no JavaScript) - `templates/` - Pure HTML templates (no JavaScript)
- `static/` - CSS styling and navigation icons - `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 ### 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: **`gallery_view()` function** (viewer/views.py:65-189) handles both:
1. **Directory browsing** when path points to folder: 1. **Directory browsing** when path points to folder:
- Lists subdirectories and images - Lists subdirectories and images
- Supports search with recursive directory scanning (viewer/views.py:32-52) - Supports search with recursive directory scanning (`viewer/directory.py:do_recursive_search`)
- Paginates images at 28 per page (7 columns × 4 rows) - Does not use server-side pagination; the gallery returns full image lists and templates render them in a grid
- Converts flat image lists to table rows for HTML rendering - Converts image lists to structured context used by templates
2. **Image viewing** when path points to file: 2. **Image viewing** when path points to file:
- Displays single image with prev/next navigation - Displays single image with prev/next navigation
- Finds sibling images in same directory - Finds sibling images in same directory
- Links to full-resolution image - 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 ### Thumbnail Generation
**Lazy generation approach** (viewer/utils.py): **Lazy generation approach** (viewer/utils.py):
- Thumbnails created on-demand when viewing gallery - 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 - Uses Pillow for image processing
- Fast extension-based image detection (no MIME-type I/O) - Fast extension-based image detection (no MIME-type I/O)