new copilot-instructions.md file
Massimo Melina committed
Nov 21, 2025 at 09:07 UTC
dc712b9a4607d0bdd98715f003a75b7fc98431fe
1 file changed
+72
.github/copilot-instructions.md
new
+72
@@ -0,0 +1,72 @@
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 -->