warpbox/DEVELOPMENT.md

# WarpBox Development Rules

This guide exists for contributors and LLM agents doing behavior-preserving
cleanup. It complements [docs/tech.md](docs/tech.md), which maps the current
implementation.

## Cleanup Principles

- Keep systems boring and obvious.
- Prefer short files grouped by one clear responsibility.
- Prefer narrow helpers over clever abstraction.
- Keep related functions physically close.
- Split files when one file mixes multiple domains.
- Avoid huge utility drawers where unrelated helpers gather.
- Do behavior-preserving cleanup before feature work.
- Use tests before and after each cleanup slice.

Cleanup is not feature work. Do not change runtime behavior unless the task
explicitly says to fix behavior.

## File Responsibility Goals

Files should not mix:

- UI and state.
- Transport and rendering.
- Validation and routing.
- Filesystem operations and business rules.
- Admin workflows and public box workflows.

When a file is large and contains multiple concerns, prefer splitting by
responsibility. Use comment regions only when a file is cohesive and splitting
would make it harder to follow.

Previously split cleanup targets:

- `static/js/app.js` now bootstraps `static/js/upload/`.
- `static/css/upload.css` now lives under `static/css/upload/` and `static/css/components/`.
- `lib/server/handlers.go` is split by handler responsibility.
- `lib/boxstore/store.go` is split by storage responsibility.
- `lib/server/admin.go` is split by admin responsibility.
- `lib/config/config.go` is split by config responsibility.

Do not refactor multiple systems in one cleanup slice.

## Comment and JSDoc Guidance

Add comments for:

- Behavior rules that are easy to break.
- Edge cases.
- Concurrency or background worker behavior.
- Security-sensitive choices.
- Non-obvious product decisions.

Avoid comments that restate code. Prefer clear names and small functions first.
Use JSDoc only when it clarifies non-obvious inputs, outputs, or side effects.

## Go Rules

- Keep public routes stable.
- Keep environment variable names stable.
- Keep API response shapes stable.
- Keep manifest JSON field names stable.
- Keep storage directory layout stable.
- Keep handler files focused on one handler category.
- Keep route registration separate from validation and business logic.
- Return clear wrapped errors when context helps debugging.
- Avoid package moves unless the cleanup slice is specifically about package
  ownership.
- Run `gofmt`, `go vet`, and `go test` through `./check.sh`.

Server handler files:

- `pages.go`
- `downloads.go`
- `uploads.go`
- `box_auth.go`
- `validation.go`
- `retention.go`

Keep `lib/server/handlers.go` absent unless there is a deliberate reason to
reintroduce a cohesive handler file.

## JavaScript Rules

- Use vanilla JavaScript only.
- Do not add a build step.
- Keep browser scripts loaded directly by templates.
- Avoid new globals; centralize mutable upload state when splitting.
- Keep DOM queries/rendering separate from API calls and upload orchestration.
- Prefer an action map over long action `if` chains when cleaning event code.
- Share generic UI helpers through `static/js/warpbox-ui.js`.
- Preserve existing data attributes and template contracts unless explicitly
  changing behavior.

Target upload split when that cleanup slice is chosen:

- `static/js/upload/state.js`
- `static/js/upload/dom.js`
- `static/js/upload/files.js`
- `static/js/upload/api.js`
- `static/js/upload/upload-flow.js`
- `static/js/upload/options.js`
- `static/js/upload/popups.js`
- `static/js/upload/terminal.js`
- `static/js/upload/events.js`
- `static/js/app.js` as bootstrap only

## CSS Rules

- Keep shared styles in shared files.
- Keep page-specific styles page-scoped.
- Avoid duplicated popup, toast, button, and window rules.
- Use page prefixes for page styles:
  - `upload-`
  - `box-`
  - `admin-`
- Keep visual changes out of behavior-preserving cleanup unless the cleanup
  slice is CSS-only.
- Preserve template class names unless the same slice updates every use.

Target CSS split when that cleanup slice is chosen:

- `base.css`
- `window.css`
- `components/buttons.css`
- `components/popups.css`
- `components/toast.css`
- `upload/layout.css`
- `upload/queue.css`
- `upload/options.css`
- `upload/dialogs.css`
- `upload/responsive.css`
- `box.css`
- `admin.css`

## Template Rules

- Keep server-rendered HTML simple.
- Do not rename public routes during cleanup.
- Do not change form field names or data attributes unless the matching Go and
  JavaScript code changes in the same slice.
- Keep static CSS and JS loading explicit.
- Avoid hidden behavior changes through template conditionals.

Current loading model:

- Go loads templates from `templates/*.html`.
- Gin serves `/static` from `./static` with gzip middleware.
- Templates link CSS directly from `/static/css/...`.
- Templates load browser JavaScript directly from `/static/js/...`.
- There is no JavaScript or CSS build step.

## Safety Rules

- Inspect repository structure before editing.
- Identify relevant files for the current cleanup slice.
- Identify how JavaScript and CSS are loaded before frontend cleanup.
- Identify available test/check commands before editing.
- Summarize the intended change before editing.
- Make the smallest useful change.
- Do not rename public routes.
- Do not rename environment variables.
- Do not change API response shapes.
- Do not change manifest JSON field names.
- Do not change storage directory layout.
- Do not add frontend tooling during cleanup.
- Do not rewrite working code just to make it look different.
- Do not mix unrelated cleanup areas in one change.
- Do not claim tests passed unless they actually ran.

## Definition of Done

For each cleanup slice:

- Change scope matches one cleanup area.
- Behavior is unchanged unless the slice is explicitly a fix.
- Files have clearer responsibility than before.
- Comments explain only non-obvious rules or risks.
- Tests or checks were run and recorded.
- Any failed command is recorded with the exact reason.
- Next cleanup slice is clear.