mirror of
https://github.com/pi-hole/web.git
synced 2026-08-23 14:51:12 +01:00
Adam Warnerandyubiuser
03e4a6be95
Co-authored-by: yubiuser <yubiuser@users.noreply.github.com> Signed-off-by: Adam Warner <github@promofaux.dev>
53 lines
2.8 KiB
Markdown
53 lines
2.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project overview
|
|
|
|
Pi-hole's web admin interface. Pages are Lua Pages (`.lp` files) rendered server-side by the embedded web server inside FTL (`pihole-FTL`); the frontend logic is plain JavaScript talking to FTL's REST API.
|
|
|
|
## Repository layout
|
|
|
|
- `*.lp` - the pages themselves (Lua Pages, rendered by FTL)
|
|
- `scripts/js/` - page JavaScript
|
|
- `scripts/lua/` - shared Lua code (layout, helpers)
|
|
- `style/` - CSS, including `style/themes/` for the selectable themes
|
|
- `img/` - images and icons
|
|
- `vendor/` - third-party assets; do not hand-edit vendored files
|
|
|
|
## Dev environment tips
|
|
|
|
- The interface cannot run standalone: it is served by a running FTL instance. Point a Pi-hole installation (or Docker container) at your checkout to test changes in a browser.
|
|
- Run `npm install` once to set up the lint toolchain.
|
|
- CSS vendor prefixes are generated with `npm run prefix`; do not add them by hand.
|
|
- All data shown in the interface comes from FTL's REST API. Do not invent endpoints; check the [FTL API documentation](https://ftl.pi-hole.net/development/docs/) (or `/api/docs` on your own instance) or the FTL repository.
|
|
|
|
## Testing instructions
|
|
|
|
- Run `npm test` (prettier in check mode plus xo). CI enforces both.
|
|
- Auto-fix with `npm run prettier:fix` and `npm run xo:fix`.
|
|
- Verify changes in a browser against a running FTL instance.
|
|
- Test in both light and dark themes when touching styling.
|
|
|
|
## PR instructions
|
|
|
|
- Base all work on the `development` branch; pull requests target `development`.
|
|
- Read the [contributors guide](https://docs.pi-hole.net/guides/github/contributing/)
|
|
- Every commit must be signed off (DCO): use `git commit -s`.
|
|
- Run `npm test` before committing.
|
|
- Use Unix line endings (LF).
|
|
- Code is licensed under the EUPL 1.2; contributions must be compatible.
|
|
- Changes that need new API capabilities require a matching FTL pull request; note the cross-repo dependency in both PRs.
|
|
- The correct project spelling is "Pi-hole" (capital P, lowercase h, hyphen).
|
|
|
|
## Security considerations
|
|
|
|
- Everything rendered in the interface may contain attacker-influenced data (hostnames, query names, list contents). Escape output; never interpolate API data into HTML or Lua templates unescaped.
|
|
- Authentication and session handling are FTL's responsibility; do not add client-side logic that assumes or bypasses it.
|
|
- If you believe you have found a vulnerability, do not open a public issue or PR; report it privately per the organisation's security policy (disclosure@pi-hole.net).
|
|
|
|
## Common pitfalls
|
|
|
|
- Treating `.lp` files as static HTML; they are Lua-templated and rendered by FTL.
|
|
- Editing files under `vendor/` or hand-writing vendor prefixes instead of using the npm scripts.
|
|
- Skipping `npm test`; CI will reject prettier/xo failures.
|
|
- Forgetting the DCO sign-off on commits.
|