NibasaViewer/AGENTS.md

AGENTS.md

Guidance for coding agents working in NibasaViewer. This document is intentionally explicit so tasks can be completed with minimal repo discovery.

1) Project Snapshot

• Stack: Python 3 + Django 4.2.
• App layout: single app, viewer.
• Data model: filesystem-first gallery; images/folders are not stored in Django models.
• Frontend constraint: minimize JavaScript dependencies; Bootstrap bundled JS is allowed when required, and custom JavaScript should be avoided unless explicitly requested.
• Auth: Django built-in auth; gallery views are login-protected.
• Image flow: originals from GALLERY_ROOT, thumbnails cached in THUMBNAILS_ROOT.

2) Source of Truth and Rule Files

• Primary in-repo agent guidance exists in CLAUDE.md.
• AGENTS.md (this file) complements CLAUDE.md for day-to-day agent execution.
• Cursor rules search result: no .cursorrules and no files in .cursor/rules/.
• Copilot rules search result: no .github/copilot-instructions.md present.
• If Cursor/Copilot rule files are added later, treat them as additional required constraints.

3) Environment and Setup Commands

• Create venv: .venv/bin/python -m venv .venv
• Activate venv (bash): source .venv/bin/activate
• Install deps: pip install -r requirements.txt
• Apply migrations: .venv/bin/python manage.py migrate
• Run server: .venv/bin/python manage.py runserver

Local configuration is loaded from .env via .venv/bin/python-dotenv.

Use this minimum .env content for gallery paths:

GALLERY_ROOT=/path/to/images
THUMBNAILS_ROOT=/path/to/thumb-cache

Notes:

• GALLERY_ROOT and THUMBNAILS_ROOT are parsed as pathlib.Path in settings.py.
• Both are optional at import time and default to None when unset/empty.
• Paths do not need to be inside BASE_DIR.

4) Build / Lint / Test Commands

There is no dedicated linter or formatter config in-repo (no ruff, flake8, black, mypy, pyright, tox, or pytest config files detected).

Use these commands as the standard validation set:

• 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: .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 .venv/bin/python manage.py test ... style labels over introducing a second test runner.

5) Operational Commands

• Pre-generate thumbnails: .venv/bin/python manage.py makethumbnails
• Create auth user (shell):
  • .venv/bin/python manage.py shell
  • from django.contrib.auth.models import User
  • User.objects.create_user('<USERNAME>', '<EMAIL>', '<PASSWORD>')
• Collect static files (deploy-time): .venv/bin/python manage.py collectstatic

6) Architecture and Change Boundaries

• Keep gallery metadata in filesystem, not DB tables.
• Do not introduce image/folder models unless explicitly requested by humans.
• Keep URL/data flow consistent:
  • /imgs/ -> GALLERY_ROOT
  • /thumbs/ -> THUMBNAILS_ROOT
  • /gallery/ -> directory browsing and image view routing
• Preserve lazy thumbnail generation behavior unless task explicitly changes performance strategy.

Recent changes notes

• The image view was refactored to match the gallery layout and styling; viewer/templates/image_view.html now uses the shared viewer/static/css/styles.css file and Bootstrap/Font Awesome includes like gallery_view.html.
• _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)

Imports

• Use grouped imports with section comments where practical:
  • Standard library imports
  • Third-party/Django imports
  • Project/local imports
• Keep import order deterministic within each group.
• Follow existing style in touched file; do not mass-reformat untouched files.

Formatting

• Follow existing formatting conventions in each file.
• Current codebase uses a traditional style with explicit spacing and readability comments.
• Avoid introducing unrelated formatting churn in files not functionally changed.
• Keep lines readable; wrap long imports or argument lists clearly.

Naming

• Functions/variables: snake_case.
• Constants: UPPER_SNAKE_CASE (see CELLS_PER_ROW, THUMB_SIZE).
• Class names: PascalCase.
• URL names: descriptive snake_case names (gallery_view_root, gallery_view_path).

Types and Data Shapes

• pathlib.Path is the preferred filesystem primitive.
• Accept str inputs only when ergonomics require it; normalize to Path early.
• Type hints are not strictly enforced across the repo; add them when they clarify non-obvious APIs.
• Do not introduce heavy typing frameworks or strict type-checking configs unless asked.

Error Handling

• Catch specific exceptions when behavior should differ by failure mode.
• Use broad except Exception only for intentionally best-effort operations (e.g., thumbnail generation), and keep side effects minimal.
• Never swallow exceptions in critical control paths without rationale.
• User-facing 404/invalid-path behavior should remain explicit and predictable.

Django View and URL Practices

• Protect gallery routes with @login_required unless requirement changes.
• Keep view context keys explicit and template-friendly.
• Preserve pagination constants and behavior unless task explicitly changes UX.
• Use redirect/render idioms already established in viewer/views.py.

Template / Frontend Constraints

• Minimize JavaScript dependencies wherever possible.
• Bootstrap's own bundled JavaScript is allowed when needed for UI behaviors (offcanvas/dropdowns/tooling).
• Avoid custom project JavaScript unless explicitly requested.
• Keep HTML/CSS compatible with older browsers; prefer conservative layout features.
• Maintain dark-theme image-viewing emphasis and existing navigation metaphors.

8) Performance Expectations

• Prefer extension-based image filtering (is_image_file) over MIME-content probing.
• Avoid repeated heavy filesystem traversals in hot request paths when simple caching/slicing works.
• Keep thumbnail generation on-demand unless batch generation is requested.

9) Safety and Config Hygiene

• Never commit secrets or production-specific local settings.
• Keep .env local and out of version control; use .env.example as a template.
• Avoid destructive git operations unless explicitly requested.
• Do not revert unrelated working tree changes made by humans.

10) Agent Workflow Checklist

When implementing a change, follow this minimum loop:

1. Read relevant files and preserve local conventions.
2. Make the smallest change that satisfies the request.
3. Run focused validation commands first, then broader checks.
4. Report what changed, why, and exactly which commands were run.

Suggested pre-handoff command bundle:

• .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.