From ad339133f1c80e8a0bbfdab95b7aa07dff46e963 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Wed, 15 Oct 2025 15:51:06 -0400 Subject: [PATCH] Document logging channels and dev mode flow --- AGENTS.md | 7 ++++++ README.md | 16 ++++++++++-- docs/logging.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 docs/logging.md diff --git a/AGENTS.md b/AGENTS.md index f01fc6b1..78007417 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,13 @@ This guide tells AI agents how to keep bitvid aligned with the current product d * **Unstable** is our experimentation lane. Gate risky behavior behind feature flags defined in `js/constants.js` and document the toggle/rollback plan in PR descriptions. * **Emergency response:** If a change regresses URL-first playback or breaks magnet parsing, revert immediately, call this out in the PR, and annotate the AGENTS.md changelog with remediation tips. **Note:** These regressions usually surface in dev logs and tests around playback/magnet helpers—reference them when triaging so future agents don’t repeat the mistake. +### Browser logging policy + +* Route every browser log through `js/utils/logger.js`. Do **not** call `console.*` directly. +* Use `logger.dev.*` for diagnostics that should disappear in production (flagged by `IS_DEV_MODE`/`isDevMode`). Use `logger.user.*` for operator-facing warnings and errors that must reach production consoles. +* Before promoting a build, flip `IS_DEV_MODE` in `config/instance-config.js` to match the target environment so `window.__BITVID_DEV_MODE__` and the logger channels behave correctly. +* Review and follow [`docs/logging.md`](docs/logging.md) whenever you add new logging or touch inline scripts. + ## 2. Mission: URL‑First Playback with WebTorrent Fallback * **Goal:** Always deliver smooth playback while keeping hosting costs low. diff --git a/README.md b/README.md index 965b6e5f..610695a7 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,11 @@ artifacts. - Central place for instance-specific values like the Super Admin npub and the default whitelist-only mode setting. Update the documented exports here when preparing a new deployment. + - Flip `IS_DEV_MODE` to `false` before shipping production builds. The flag + flows into `js/config.js` as `isDevMode`, seeds the + `window.__BITVID_DEV_MODE__` global for inline scripts, and gates whether the + dev logging channel emits to the console. See + [`docs/logging.md`](docs/logging.md) for rollout guidance. - Tune `PLATFORM_FEE_PERCENT` (0–100) to keep a percentage of Lightning tips. When the fee is positive, bitvid routes the platform’s split to `PLATFORM_LUD16_OVERRIDE`, so set it to the Lightning address that should @@ -177,8 +182,15 @@ artifacts. the fee at `0` to pass through every satoshi. - Populate `DEFAULT_RELAY_URLS_OVERRIDE` with WSS URLs to replace the bundled relay bootstrap list. Keep it empty to stick with the upstream defaults. -- **`config.js`**: - - Toggle `isDevMode` for development (`true`) or production (`false`). +- **`js/config.js`**: + - Re-exports `isDevMode` (derived from `IS_DEV_MODE`) for modules, publishes + `window.__BITVID_DEV_MODE__`, and centralizes the global configuration + surface. +- **`js/utils/logger.js`**: + - Provides the shared `logger` utility. Route user-facing errors through + `logger.user` and keep experimental diagnostics on `logger.dev` so operators + can quiet development noise in production. Details live in + [`docs/logging.md`](docs/logging.md). - **`js/constants.js`**: - Source for browser-safe tracker lists and feature flags that govern WebTorrent behavior. - **Magnet helpers**: diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 00000000..f24b3f71 --- /dev/null +++ b/docs/logging.md @@ -0,0 +1,66 @@ +# Logging and Dev-Mode Guidance + +This document explains how bitvid routes browser logs, how inline scripts can +re-use the shared logger, and what operators must do with the dev-mode flag when +promoting builds. + +## Picking the right channel + +bitvid ships a frozen logger at `js/utils/logger.js` with two channels: + +- `logger.dev`: Emits only when `IS_DEV_MODE` is truthy. Use this channel for + verbose traces, performance probes, and feature flag experimentation that + should disappear from production consoles. +- `logger.user`: Always available and automatically prefixes output with + `[bitvid]`. Use this channel for operator-facing warnings and errors that help + diagnose issues in production. + +When adding new messages, classify them by the audience: + +| Scenario | Recommended channel | Notes | +| --- | --- | --- | +| Debugging a new feature locally | `logger.dev.info`/`logger.dev.log` | Remove or downgrade before launching if they no longer serve a purpose. | +| Non-fatal recoverable issues users should investigate | `logger.user.warn` | Provide actionable context so operators know what failed. | +| Fatal errors that block playback or payments | `logger.user.error` | Escalate with a clear message and include relevant IDs or URLs. | +| Metrics or noisy traces that only help during QA | `logger.dev.*` | Wrap expensive logging in conditional checks when possible. | + +Avoid direct `console.*` calls—routing everything through the logger keeps the +production console clean and guarantees dev-mode gates behave consistently. + +## Using the logger from inline scripts + +The logger is exposed as a frozen global so inline scripts can share the same +API without additional bundling: + +```js +const { dev, user } = window.bitvidLogger; + +dev.log("rendering upload modal preview"); +user.warn("Playback manifest missing expected resolution tag"); +``` + +If you need to guard logic by environment, rely on the companion global set in +`js/config.js`: + +```js +if (window.__BITVID_DEV_MODE__) { + window.bitvidLogger.dev.info("Hydrating admin widgets in dev mode"); +} +``` + +The globals are populated as soon as `js/config.js` loads. Check for their +existence before using them in third-party contexts that may execute earlier. + +## Adjusting the dev-mode flag for deployments + +The source of truth lives in `config/instance-config.js`: + +- Set `IS_DEV_MODE = true` while developing locally so the dev logger and other + diagnostics are available. +- Flip `IS_DEV_MODE = false` before shipping a production build. This change + propagates to `isDevMode` (the module export), `window.__BITVID_DEV_MODE__`, + and `logger.dev`, silencing development-only messages. + +Always commit the flag change alongside deployment-ready configuration tweaks. +Forgetting to update the flag leaves verbose traces in user consoles and can +expose experimental behavior intended only for QA environments.