| 1 | <!-- Copilot / AI agent instructions for the HFS repository --> |
| 2 | |
| 3 | # HFS — AI contributor quick guide |
| 4 | |
| 5 | This project is the HFS (HTTP File Server) monorepo. The goal of this file is to give an AI coding agent the concise, practical knowledge needed to be productive immediately. |
| 6 | |
| 7 | Key facts |
| 8 | - **Runtime:** Node.js (requirement enforced in `src/index.ts`) — minimum `18.15.0` (see `package.json`). |
| 9 | - **Workspaces:** Root `package.json` uses npm workspaces: `admin`, `frontend`, `shared`, `mui-grid-form`. |
| 10 | - **Language:** TypeScript for server and parts of frontend; built outputs are emitted to `dist/`. |
| 11 | |
| 12 | Architecture (big picture) |
| 13 | - Server: `src/` contains the Koa-based HTTP server. Entry point: `src/index.ts`. Middlewares are composed here (session, plugins, throttler, API mounting). |
| 14 | - APIs: API endpoints are split into `frontEndApis` and `adminApis` and mounted together under `API_URI` (see `src/index.ts` and `src/frontEndApis.ts`). Avoid duplicating endpoint names — code asserts no clashes. |
| 15 | - GUI: Two separate front-end apps are served: the admin UI in `admin/` and the public frontend in `frontend/`. Serving logic is in `src/serveGuiAndSharedFiles.ts` and `src/serveGuiFiles.ts` and uses environment vars `FRONTEND_PROXY` and `ADMIN_PROXY` for dev-mode proxies. |
| 16 | - VFS & files: Virtual filesystem logic lives in `src/vfs.ts` and is heavily used by `serveGuiAndSharedFiles.ts`, `serveFile.ts`, upload handlers, and plugins. |
| 17 | - Plugins: `plugins/` contains built-in plugins. Plugin hooks are wired via `src/plugins.ts` and `pluginsMiddleware` in `src/index.ts`. |
| 18 | - Packaging: `build-server` compiles TypeScript into `dist/` and `dist` is used for producing binaries with `pkg` (see `package.json` scripts and `afterbuild.js`). |
| 19 | |
| 20 | Developer workflows & the exact commands to use |
| 21 | - Quick dev server (auto-restarts on server TS changes): |
| 22 | - `npm run watch-server` (uses `nodemon` + `tsx`). |
| 23 | - To run proxied for Vite frontends: `npm run watch-server-proxied` (sets `FRONTEND_PROXY` and `ADMIN_PROXY`). |
| 24 | - Start frontends individually (workspace): |
| 25 | - Admin: `npm run start-admin` (runs `npm run start --workspace=admin`). |
| 26 | - Frontend: `npm run start-frontend`. |
| 27 | - Build everything (packaging + tests): `npm run build-all` — this runs audits, compiles server, runs tests, and builds frontends/admin. |
| 28 | - Build server only: `npm run build-server` (emits `dist/`). |
| 29 | - Run tests: |
| 30 | - Unit / node tests: `npm test` (uses `tsx` test harness). For tests that need a running server: `npm run test-with-server` (the script launches `dist/src` and runs tests against it, then shuts down the server). |
| 31 | - Playwright UI tests: `npm run test-ui` (calls `npx playwright test frontend` and serial tests). Use `npm run test-with-ui` to get Playwright UI runner. |
| 32 | - Packaging / distribution: `npm run dist` and related `dist-*` scripts use `pkg` to create OS-specific binaries. |
| 33 | |
| 34 | Repository & coding conventions specific to this project |
| 35 | - Entrypoint and middleware pattern: the server composes many small Koa middlewares; prefer implementing features as middlewares that plug into `src/index.ts` unless they are pure library code. |
| 36 | - API registration: add endpoints to either `frontEndApis` or `adminApis` (do not modify both). Search for `frontEndApis` / `adminApis` to see existing patterns. |
| 37 | - Config: configuration keys and defaults live in `src/config.ts` and `central.json`. `config.md` documents runtime config. The runtime config file is `config.yaml` in the cwd by default. |
| 38 | - Environment flags: |
| 39 | - `DEV` / `HFS_DEBUG` — toggles extra logging and dev-mode behaviors. |
| 40 | - `FRONTEND_PROXY`, `ADMIN_PROXY` — used when running server in dev while frontend is served by Vite. |
| 41 | - `COOKIE_SIGN_KEYS` — comma-separated keys for session signing. |
| 42 | - `DISABLE_UPDATE` — useful for containerized builds. |
| 43 | - Frontend serving: the server may proxy to vite during development. `serveGuiAndSharedFiles.ts` contains the heuristics (look for `DEV` checks and `FRONTEND_PROXY`). |
| 44 | |
| 45 | Important files to inspect for any change or feature |
| 46 | - `src/index.ts` — server bootstrap and middleware composition. |
| 47 | - `src/serveGuiAndSharedFiles.ts` and `src/serveGuiFiles.ts` — how frontend/admin apps are discovered and served. |
| 48 | - `src/vfs.ts` — virtual filesystem model and path/url translation (`urlToNode`, `walkNode`). |
| 49 | - `src/plugins.ts` and `plugins/` — plugin lifecycle and example plugins. |
| 50 | - `src/*Apis.ts` (e.g., `adminApis.ts`, `frontEndApis.ts`) — API endpoints and permission checks. |
| 51 | - `package.json` (root) — scripts, workspace config, Node engine requirement. |
| 52 | - `dev.md` and `dev-plugins.md` — developer-specific notes and plugin authoring tips. |
| 53 | |
| 54 | Patterns & gotchas discovered in the codebase |
| 55 | - Avoid changing endpoints directly in router code; add handlers to the appropriate `*Apis` module so the `API_URI` mounting remains consistent. |
| 56 | - The server expects to be started with cwd containing `config.yaml` (or `--cwd` passed). Tests use `tests/work` as a temporary cwd — mimic that pattern when writing tests. |
| 57 | - Many operations emit events via `events` (an EventEmitter). Use `events.emit` and `events.on` to participate in cross-cutting behaviors. |
| 58 | - Binary packaging relies on `pkg` and expects assets declared in `package.json` `pkg.assets`. If adding static assets, update both `files` and `pkg.assets` as needed. |
| 59 | |
| 60 | How to propose changes safely |
| 61 | - For server-side code changes: run `npm run watch-server` locally and exercise APIs with the frontend or curl. If your change affects front-end bundles, use `npm run build-server` + `npm run build-admin` / `npm run build-frontend`. |
| 62 | - For UI changes: run the appropriate workspace dev server (`npm run start-admin` or `npm run start-frontend`) and use `watch-server-proxied` on the server to test integrated behavior. |
| 63 | - For changes that impact distribution (binaries), run `npm run build-all` and `npm run dist-uncommitted` on CI-like environment; packaging is stateful and can modify `dist/` and stashes. |
| 64 | |
| 65 | Examples (copyable) |
| 66 | - Start dev server + admin dev UI (two terminals): |
| 67 | - Terminal 1: `npm run start-admin` |
| 68 | - Terminal 2: `npm run watch-server-proxied` |
| 69 | - Run integration tests that expect a running server (single command): |
| 70 | - `npm run build-server && npm run test-with-server` |
| 71 | |
| 72 | <!-- End of file --> |