diff --git a/README.md b/README.md index 32c951a5..6c5bdbfb 100644 --- a/README.md +++ b/README.md @@ -431,8 +431,11 @@ artifacts now that the deploy pipeline owns the build step. preparing a new deployment. - See [`docs/instance-config.md`](docs/instance-config.md) for a full reference of every setting and how to tune it. - - Flip `IS_DEV_MODE` to `false` before shipping production builds. The flag - flows into `js/config.js` as `isDevMode`, seeds the + - `IS_DEV_MODE` and `IS_VERBOSE_DEV_MODE` default to `false` for production. + If you need dev logging in a staging or QA build without editing source, + inject `window.__BITVID_DEV_MODE_OVERRIDE__` and/or + `window.__BITVID_VERBOSE_DEV_MODE_OVERRIDE__` before `js/config.js` loads. + 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. diff --git a/config/instance-config.js b/config/instance-config.js index a391e0a2..c953973d 100644 --- a/config/instance-config.js +++ b/config/instance-config.js @@ -17,11 +17,13 @@ * Whether the current deployment should enable developer-centric behavior. * * When `true`, bitvid surfaces extra logging, debug helpers, and experimental - * UI affordances intended for development environments. Set the value to - * `false` before deploying to production so that end users receive the stable - * experience. Downstream modules read this flag via `js/config.js`. + * UI affordances intended for development environments. Leave the value + * `false` for production so end users receive the stable experience; use the + * runtime overrides documented in `js/config.js` when you need to toggle dev + * mode without editing this file. Downstream modules read this flag via + * `js/config.js`. */ -export const IS_DEV_MODE = true; +export const IS_DEV_MODE = false; /** * Whether development builds should surface extra verbose diagnostics. @@ -29,8 +31,10 @@ export const IS_DEV_MODE = true; * Set this to `true` to keep high-volume development warnings (like COUNT * request failures) visible in the console. Flip it to `false` when you want * a quieter dev mode without disabling other development helpers entirely. + * Use the runtime override documented in `js/config.js` if you need to toggle + * verbosity without editing this file. */ -export const IS_VERBOSE_DEV_MODE = true; +export const IS_VERBOSE_DEV_MODE = false; /** * Whether the current deployment should operate in lockdown mode. diff --git a/docs/instance-config.md b/docs/instance-config.md index c8997e51..05da1ec3 100644 --- a/docs/instance-config.md +++ b/docs/instance-config.md @@ -28,14 +28,30 @@ an operator might change it. debug affordances. The value is re-exported as `isDevMode` in `js/config.js` and controls `window.__BITVID_DEV_MODE__` as well as logger routing. - - **Why change it:** Set to `false` for production builds so only the stable - UX and user-facing logging remain. + - **Why change it:** Defaults to `false` for production builds. Set to `true` + for local development, or use the runtime override described below to + toggle dev mode without editing this file. - **`IS_VERBOSE_DEV_MODE`** - **What it does:** Enables high-volume diagnostics inside dev mode (for example, repeated COUNT failures). - **Why change it:** Keep `true` while debugging noisy workflows and set to `false` when you want a quieter dev console without disabling dev mode. + Defaults to `false` for production. + +To override the dev flags at runtime (for example in a staging build) without +changing `config/instance-config.js`, inject one or both of the following +globals **before** `js/config.js` loads: + +```html + +``` + +The overrides accept boolean values or the strings `"true"` / `"false"` so they +can be injected at build time. - **`IS_LOCKDOWN_MODE`** - **What it does:** Toggles a lockdown posture that limits access and switches diff --git a/docs/logging.md b/docs/logging.md index 0f5f81bb..5afd4d18 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -59,10 +59,23 @@ 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. +- Keep `IS_DEV_MODE = false` for production builds. This value 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. + +If you need to enable dev logging without editing `config/instance-config.js`, +inject a runtime override before `js/config.js` loads: + +```html + +``` + +Overrides accept boolean values or the strings `"true"` / `"false"` so they can +be injected by a build pipeline. diff --git a/js/config.js b/js/config.js index 73d5fe76..d8c31343 100644 --- a/js/config.js +++ b/js/config.js @@ -47,10 +47,39 @@ import { export const WATCH_HISTORY_VERSION_TAG_VALUE = "2"; -export const isDevMode = Boolean(IS_DEV_MODE); +const runtimeScope = typeof globalThis === "undefined" ? null : globalThis; + +const parseBooleanOverride = (value) => { + if (typeof value === "boolean") { + return value; + } + if (typeof value === "string") { + const normalized = value.trim().toLowerCase(); + if (normalized === "true") { + return true; + } + if (normalized === "false") { + return false; + } + } + return null; +}; + +const devModeOverride = parseBooleanOverride( + runtimeScope?.__BITVID_DEV_MODE_OVERRIDE__ +); +const verboseDevModeOverride = parseBooleanOverride( + runtimeScope?.__BITVID_VERBOSE_DEV_MODE_OVERRIDE__ +); + +export const isDevMode = + devModeOverride === null ? Boolean(IS_DEV_MODE) : devModeOverride; export { IS_DEV_MODE }; -export const isVerboseDevMode = Boolean(IS_VERBOSE_DEV_MODE); +export const isVerboseDevMode = + verboseDevModeOverride === null + ? Boolean(IS_VERBOSE_DEV_MODE) + : verboseDevModeOverride; export { IS_VERBOSE_DEV_MODE }; export const isLockdownMode = Boolean(IS_LOCKDOWN_MODE);