From e88374e24647d6c79fa6c646af195d922d494553 Mon Sep 17 00:00:00 2001 From: Adam Outler Date: Sun, 21 Sep 2025 17:40:09 -0400 Subject: [PATCH] Document standard plugin formats and logging practices Added standard plugin formats and logging guidelines for AI assistants. --- .github/copilot-instructions.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d7f55ba5..f700f7ef 100755 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -20,6 +20,20 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, ` - Data contract: scripts write `/app/log/plugins/last_result..log` (pipe‑delimited: 9 required cols + optional 4). Use `front/plugins/plugin_helper.py`’s `Plugin_Objects` to sanitize text and normalize MACs, then `write_result_file()`. - Device import: define `database_column_definitions` when creating/updating devices; watched fields trigger notifications. +### Standard Plugin Formats +* publisher: Sends notifications to services. Runs `on_notification`. Data source: self. +* dev scanner: Creates devices and manages online/offline status. Runs on `schedule`. Data source: self / SQLite DB. +* name discovery: Discovers device names via various protocols. Runs `before_name_updates` or on `schedule`. Data source: self. +* importer: Imports devices from another service. Runs on `schedule`. Data source: self / SQLite DB. +* system: Provides core system functionality. Runs on `schedule` or is always on. Data source: self / Template. +* other: Miscellaneous plugins. Runs at various times. Data source: self / Template. + +### Plugin logging & outputs +- Always log via `mylog()` like other plugins do (no `print()`). Example: `mylog('verbose', [f'[{pluginName}] In script'])`. +- Collect results with `Plugin_Objects.add_object(...)` during processing and call `plugin_objects.write_result_file()` exactly once at the end of the script. +- Prefer to log a brief summary before writing (e.g., total objects added) to aid troubleshooting; keep logs concise at `verbose` level unless debugging. + +- Do not write ad‑hoc files for results; the only consumable output is `last_result..log` generated by `Plugin_Objects`. ## API/Endpoints quick map - Flask app: `server/api_server/api_server_start.py` exposes routes like `/device/`, `/devices`, `/devices/export/{csv,json}`, `/devices/import`, `/devices/totals`, `/devices/by-status`, plus `nettools`, `events`, `sessions`, `dbquery`, `metrics`, `sync`. - Authorization: all routes expect header `Authorization: Bearer ` via `get_setting_value('API_TOKEN')`. @@ -45,4 +59,4 @@ Backend loop phases (see `server/__main__.py` and `server/plugin.py`): `once`, ` - Logs: backend `/app/log/app.log`, plugin logs under `/app/log/plugins/`, nginx/php logs under `/var/log/*` Assistant expectations -- Reference concrete files/paths. Use existing helpers/settings. Keep changes idempotent and safe. Offer a quick validation step (log line, API hit, or JSON export) for anything you add. \ No newline at end of file +- Reference concrete files/paths. Use existing helpers/settings. Keep changes idempotent and safe. Offer a quick validation step (log line, API hit, or JSON export) for anything you add.