From 1c876a7e8aea6abac96394857d0ae7b191531f6e Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 3 Mar 2026 03:10:17 +0000 Subject: [PATCH] chore(ai): document dashboard/app.js flows via daily scheduler agent - Successfully completed docs-code-investigator agent run as scheduler. - Identified dashboard/app.js (835 LOC) and applied JSDoc tags to public methods. - Wrote module overview flow at docs/dashboard-app-overview.md. - Created required context, todo, decision, and test artifacts. - Ingested memory metrics. - Validated tests and frontend build. - Completed task publish. Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> --- dashboard/app.js | 49 +++++++++++++++++++ docs/dashboard-app-overview.md | 45 +++++++++++++++++ memory_update.json | 4 ++ src/context/CONTEXT_docs_investigator.md | 14 ++++++ src/decisions/DECISIONS_docs_investigator.md | 15 ++++++ src/test_logs/TEST_LOG_docs_investigator.md | 19 +++++++ src/todo/TODO_docs_investigator.md | 13 +++++ ...-00Z__docs-code-investigator__completed.md | 10 ++++ test-torch-config-host-8sZh1F/package.json | 1 - .../torch-config.json | 1 - .../torch/torch-config.json | 1 - test-torch-config-host-OGjeCA/package.json | 1 - .../torch-config.json | 1 - .../torch/torch-config.json | 1 - 14 files changed, 169 insertions(+), 6 deletions(-) create mode 100644 docs/dashboard-app-overview.md create mode 100644 memory_update.json create mode 100644 src/context/CONTEXT_docs_investigator.md create mode 100644 src/decisions/DECISIONS_docs_investigator.md create mode 100644 src/test_logs/TEST_LOG_docs_investigator.md create mode 100644 src/todo/TODO_docs_investigator.md create mode 100644 task-logs/daily/2026-03-03T01-00-00Z__docs-code-investigator__completed.md delete mode 100644 test-torch-config-host-8sZh1F/package.json delete mode 100644 test-torch-config-host-8sZh1F/torch-config.json delete mode 100644 test-torch-config-host-8sZh1F/torch/torch-config.json delete mode 100644 test-torch-config-host-OGjeCA/package.json delete mode 100644 test-torch-config-host-OGjeCA/torch-config.json delete mode 100644 test-torch-config-host-OGjeCA/torch/torch-config.json diff --git a/dashboard/app.js b/dashboard/app.js index 9efe9e6..f5d2b58 100644 --- a/dashboard/app.js +++ b/dashboard/app.js @@ -2,6 +2,18 @@ import { KIND_APP_DATA } from '../src/constants.mjs'; import { createElement } from './domUtils.js'; +/** + * Main Execution Flow: + * 1. Setup UI (Modals, Event Listeners) and configuration defaults. + * 2. `bootstrap()` loads `torch-config.json` and parses local storage prefs. + * 3. `init()` loops over configured relays and calls `connectToRelay()`. + * 4. WebSocket handlers listen for `LOCK_EVENT_KIND` events via NIP-01 REQ. + * 5. Incoming events are parsed (`parseLockEvent()`), de-duplicated by `dTag`, and stored. + * 6. `scheduleRender()` debounces layout updates. + * 7. `renderLocks()` creates and injects cards mapping to current system locks. + * 8. A periodic interval re-renders the UI to update TTl progress bars. + */ + // ----------------------------------------------------------------------- // Modal Logic // ----------------------------------------------------------------------- @@ -97,6 +109,11 @@ window.onclick = function(event) { } } +/** + * Fetches the TORCH.md file and renders it into the DOM using marked and DOMPurify. + * Renders an error message to the user if the fetch fails. + * @returns {Promise} + */ async function fetchDocs() { try { const response = await fetch('../src/docs/TORCH.md'); @@ -146,6 +163,11 @@ function normalizeStatus(value) { : DASHBOARD_DEFAULTS.defaultStatusView; } +/** + * Loads the dashboard configuration from a local torch-config.json file. + * Returns an empty object if no config is found or readable. + * @returns {Promise} The parsed torch-config object + */ async function loadTorchConfigFile() { const configCandidates = ['../torch-config.json', './torch-config.json']; @@ -162,6 +184,13 @@ async function loadTorchConfigFile() { return {}; } +/** + * Resolves configuration properties cascading from highest precedence (URL parameters), + * to intermediate precedence (LocalStorage), then `torch-config.json`, and finally falling + * back to hardcoded defaults. + * @param {Object} [torchConfig={}] - The JSON structure from loadTorchConfigFile() + * @returns {Object} A resolved settings dictionary containing namespace, hashtag, and relays. + */ function parseDashboardConfig(torchConfig = {}) { const params = new URLSearchParams(window.location.search); @@ -676,6 +705,15 @@ function updateConnectionBadge() { } } +/** + * Establishes a WebSocket connection to the given Nostr relay and negotiates + * a NIP-01 subscription requesting historic events within a 7 day window that + * match the current LOCK_EVENT_KIND and configured hashtag. + * Incoming events are pushed to global state lockStore and render is triggered. + * + * Automatically attempts reconnection after 5000ms if closed abruptly. + * @param {string} url - Valid WebSocket URL to connect to. + */ function connectToRelay(url) { if (!isAlive()) return; @@ -810,6 +848,11 @@ if (refreshBtn) refreshBtn.addEventListener('click', () => { // ----------------------------------------------------------------------- // Init // ----------------------------------------------------------------------- + +/** + * Initializes the dashboard connections and logic using global settings resolved + * by bootstrap(). Connects to each websocket in the RELAYS array. + */ function init() { if (!isAlive()) return; @@ -820,6 +863,12 @@ function init() { } } +/** + * Main application entrypoint. Loads async dependencies (`loadTorchConfigFile()`), + * resolves local overrides, populates config globals, updates the DOM filter fields + * with default options, and kicks off socket connectivity via `init()`. + * @returns {Promise} + */ async function bootstrap() { const torchConfig = await loadTorchConfigFile(); DASHBOARD_CONFIG = parseDashboardConfig(torchConfig); diff --git a/docs/dashboard-app-overview.md b/docs/dashboard-app-overview.md new file mode 100644 index 0000000..401fc76 --- /dev/null +++ b/docs/dashboard-app-overview.md @@ -0,0 +1,45 @@ +# Dashboard App Overview + +## What this module does +The `dashboard/app.js` module is the main entry point for the frontend UI logic of the TORCH web dashboard. It manages the configuration loading cascading from URL queries, `localStorage`, and `torch-config.json` default settings, and maintains live WebSocket connections to Nostr relays. Incoming `LOCK_EVENT_KIND` events are parsed, de-duplicated, and pushed to the UI where they render as lock cards with remaining TTL status via a periodic interval. + +## Main Execution Flow +1. **Config Setup**: `bootstrap()` loads settings via `loadTorchConfigFile()`, resolves preferences using `parseDashboardConfig()`, and populates global constants like `RELAYS` and `HASHTAG`. +2. **Relay Setup**: `init()` loops over the configured `RELAYS` and calls `connectToRelay()` for each. +3. **Data Subscription**: `connectToRelay()` opens a WebSocket, emitting a NIP-01 `REQ` for lock events tagged with the namespace over the past 7 days. +4. **Data Intake**: Incoming `EVENT` messages are parsed via `parseLockEvent()`, de-duplicated based on `dTag`, stored in `lockStore`, and logged into the `rawLog` DOM container. +5. **UI Rendering**: The receipt of events triggers `scheduleRender()`, which delegates to `renderLocks()` to build DOM nodes using `createLockCard()` for all active/filtered locks. +6. **Background Loop**: A 30s interval re-renders the DOM to decrement remaining lock TTL and update the CSS widths of progress bars. + +## Usage Snippet +```js +// Within dashboard/index.html + +``` +*(The module invokes `bootstrap()` as its final statement).* + +## Public API / Exports +*(Note: As an entrypoint module assigned via a direct `