2.3 KiB

Raw Blame History

AGENTS.md

Guidance for coding agents and automated contributors working in this repository.

Project Snapshot

Iron is a self-hosted personal cloud drive gateway with:

FastAPI backend under app/
Vite + React + TypeScript frontend under frontend/
built frontend assets served from app/web/dist/
Alembic migrations under alembic/
tests under tests/
project docs under docs/

The current stage is Product MVP Candidate. Preserve the existing desktop-first drive UX and avoid drifting back toward a generic admin dashboard.

Required Setup

Use the local virtualenv and uv cache:

UV_CACHE_DIR=.uv-cache uv venv .venv
UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python -e '.[dev]'
npm install

Common Commands

npm run build
.venv/bin/python -m pytest
.venv/bin/python scripts/ui_playwright_smoke.py
.venv/bin/python -m pytest tests/e2e/test_web_ui_playwright.py

Development Rules

Keep runtime artifacts out of Git: .venv/, node_modules/, output/, .iron-storage/, .iron-temp/, caches, and local databases.
Add or update tests in the same change as behavior changes.
For UI work, run the real-service Playwright flow and review screenshots.
Do not use naked /api/files/... media URLs for browser preview/download. Fetch file content with authorization, create an object URL, and revoke it.
Keep docs current when changing setup, architecture, test counts, or user flows.
Prefer small, focused changes over broad rewrites.

UI Quality Standard

For any meaningful Web UI change:

build frontend assets with npm run build
run ./.venv/bin/python scripts/ui_playwright_smoke.py
inspect screenshots in output/playwright/
fix layout or interaction issues found in screenshots
rerun the Playwright flow

See docs/development.md.

Documentation Expectations

README.md should stay user-facing and concise.
CONTRIBUTING.md should describe contributor workflow.
docs/README.md should index deeper docs.
docs/development.md should describe test and UI validation rules.
Avoid local absolute paths in committed Markdown.

Verification Before Finishing

At minimum, run:

npm run build
.venv/bin/python -m pytest

If UI behavior changed, also run:

.venv/bin/python scripts/ui_playwright_smoke.py

2.3 KiB Raw Blame History