| 1 | # Repository Guidelines |
| 2 | |
| 3 | ## Project Structure & Module Organization |
| 4 | Core server logic sits in `src/` (TypeScript, Koa middleware, plugins). Shared React packages live under the workspace folders `frontend/`, `admin/`, `shared/`, and `mui-grid-form/`. Runtime assets (icons, central metadata) are in the repo root; packaged plugins reside in `plugins/`. Tests use `tests/` for Node-based suites and `e2e/` + `playwright.config.ts` for UI regression coverage. Build outputs land in `dist/`; avoid committing its contents manually. |
| 5 | |
| 6 | ## Docs Map |
| 7 | - `README.md` — overview, installation, and general usage. |
| 8 | - `config.md` — configuration keys and where config files are stored (includes `server_code` for backend scripting). |
| 9 | - `dev.md` — build, dev environment, tests, and coding guidelines. |
| 10 | - `dev-plugins.md` — plugin development and API reference (backend and frontend APIs). |
| 11 | - `SECURITY.md` — security policy and reporting. |
| 12 | - Wiki — some topics are documented only on the project wiki. |
| 13 | |
| 14 | ## Build, Test, and Development Commands |
| 15 | - `npm run watch-server` — start the TypeScript server with hot reload (set `FRONTEND_PROXY`/`ADMIN_PROXY` when pairing with dev UIs). |
| 16 | - `npm run watch-server-full` — boot both React apps plus the API server for integrated development. |
| 17 | - `npm run build-server` / `npm run build-frontend` / `npm run build-admin` — compile individual targets into `dist/`. |
| 18 | - `npm run build-all` — audit dependencies, rebuild everything, run API tests, and kick off frontend/admin builds in parallel. Use a 100s timeout. |
| 19 | - `npm run test-with-server` — execute the Node test suite (`tests/test.ts`) with related server. May require escalated permissions in sandboxed environments to bind to port 81. |
| 20 | - `npm run test-ui` — launch Playwright’s headless CI. |
| 21 | |
| 22 | ## Coding Style & Naming Conventions |
| 23 | Use TypeScript/ES2022 with 4-space indentation and single quotes except when JSON compatibility is needed. Prefer async/await over promise chains and keep streaming utilities (e.g., `AsapJStream`) in dedicated modules. Name files by responsibility (`*.ts` for services, `*.spec.ts` for tests) and React components in PascalCase. Run `tsc` implicitly via the build scripts; no separate lint step exists, so keep code self-explanatory and add succinct comments only for non-obvious flows. |
| 24 | |
| 25 | ## Testing Guidelines |
| 26 | Node-side tests rely on the built-in `node --test` runner via `npm test`. Place fixtures under `tests/work` where scripts already expect them. UI coverage uses Playwright (`tests-ui`/`frontend` suites); target critical upload/download flows and plugin management. Name new tests after the behavior they assert (e.g., `plugin-disable.test.ts`). Before pushing, run at least `npm test` and, when touching UI, the relevant Playwright suite. |
| 27 | When you want to run fewer tests, use `npm run test-with-server -- --test-name-pattern="<pattern>"`. |
| 28 | If port `8081` is already in use, run the filtered suite with `npm test -- --test-name-pattern="<pattern>"` instead of `test-with-server`. |
| 29 | For full-suite regression checks, prefer a failure-focused TAP filter to reduce noise and token usage: |
| 30 | `npm test -- --test-reporter=tap 2>&1 | awk '/^not ok /{p=1} p{print} /^ok [0-9]+ - /{p=0} /^# fail [1-9]/{print}'`. |
| 31 | If failures appear, rerun the failing subset with normal/verbose output for diagnosis. |
| 32 | For long-running commands like tests/builds, use a 30s timeout unless a different value is requested. |
| 33 | Changes to the config are automatically reloaded and applied asap, no need to restart. |
| 34 | |
| 35 | ## Commit & Pull Request Guidelines |
| 36 | Recent history favors short, component-scoped subjects (`admin/plugins: faster list on get-more`). Follow that pattern: `<area>: <concise change>`. Keep commits focused and self-contained. Pull requests should describe motivation, summarize key changes, call out affected packages (`src`, `frontend`, etc.), and mention how to reproduce or verify. Include screenshots for UI changes and note which commands/tests were run. Reference GitHub issues when applicable and flag any follow-up work. |