ultimate-jekyll-manager 1.4.2 → 1.5.0

package/dist/test/suites/build/mode-helpers.test.js

@@ -11,7 +11,7 @@ module.exports = {
       name: 'helpers attach to Manager statically AND on prototype',
       run: async (ctx) => {
         const Manager = require('../../../build.js');
-        for (const name of ['isTesting', 'isDevelopment', 'isProduction', 'getVersion']) {
+        for (const name of ['getEnvironment', 'isTesting', 'isDevelopment', 'isProduction', 'getVersion']) {
           ctx.expect(typeof Manager[name]).toBe('function');
           ctx.expect(typeof Manager.prototype[name]).toBe('function');
         }
@@ -35,17 +35,69 @@ module.exports = {
       },
     },
     {
-      name: 'isDevelopment false when UJ_BUILD_MODE=true',
+      name: 'isDevelopment false / isProduction true when UJ_BUILD_MODE=true (and not testing)',
       run: async (ctx) => {
         const Manager = require('../../../build.js');
         const original = process.env.UJ_BUILD_MODE;
+        const origTest = process.env.UJ_TEST_MODE;
         try {
+          delete process.env.UJ_TEST_MODE; // isolate the build-mode branch from testing precedence
           process.env.UJ_BUILD_MODE = 'true';
           ctx.expect(Manager.isDevelopment()).toBe(false);
           ctx.expect(Manager.isProduction()).toBe(true);
         } finally {
           if (original === undefined) delete process.env.UJ_BUILD_MODE;
           else process.env.UJ_BUILD_MODE = original;
+          if (origTest !== undefined) process.env.UJ_TEST_MODE = origTest;
+        }
+      },
+    },
+    {
+      name: 'environments are mutually exclusive — testing wins under UJ_TEST_MODE',
+      run: async (ctx) => {
+        const Manager = require('../../../build.js');
+        // These tests run under UJ_TEST_MODE=true → testing wins; dev and prod are false.
+        ctx.expect(Manager.isTesting()).toBe(true);
+        ctx.expect(Manager.isDevelopment()).toBe(false);
+        ctx.expect(Manager.isProduction()).toBe(false);
+      },
+    },
+    {
+      // The core invariant of the SSOT refactor: is*() DERIVE from getEnvironment(), so they
+      // can NEVER disagree with it, and exactly one is always true. (In build-time Node `window`
+      // is undefined, so getEnvironment() resolves via the env-var fallback.)
+      name: 'invariant: is*() exactly matches getEnvironment() + mutually exclusive (every scenario)',
+      run: async (ctx) => {
+        const Manager = require('../../../build.js');
+        const prevTest = process.env.UJ_TEST_MODE;
+        const prevBuild = process.env.UJ_BUILD_MODE;
+        const prevServer = process.env.UJ_IS_SERVER;
+        const prevNode = process.env.NODE_ENV;
+        const scenarios = [
+          { env: { UJ_TEST_MODE: 'true', UJ_BUILD_MODE: 'true' }, expect: 'testing' },
+          { env: { UJ_BUILD_MODE: 'true' },                       expect: 'production' },
+          { env: { UJ_IS_SERVER: 'true' },                        expect: 'production' },
+          { env: { NODE_ENV: 'development' },                     expect: 'development' },
+          { env: {},                                              expect: 'development' }, // UJM defaults dev (signal always baked in)
+        ];
+        try {
+          for (const s of scenarios) {
+            delete process.env.UJ_TEST_MODE; delete process.env.UJ_BUILD_MODE;
+            delete process.env.UJ_IS_SERVER; delete process.env.NODE_ENV;
+            for (const k of Object.keys(s.env)) process.env[k] = s.env[k];
+            const e = Manager.getEnvironment();
+            ctx.expect(e).toBe(s.expect);
+            ctx.expect(Manager.isDevelopment()).toBe(e === 'development');
+            ctx.expect(Manager.isTesting()).toBe(e === 'testing');
+            ctx.expect(Manager.isProduction()).toBe(e === 'production');
+            const trueCount = [Manager.isDevelopment(), Manager.isTesting(), Manager.isProduction()].filter(Boolean).length;
+            ctx.expect(trueCount).toBe(1);
+          }
+        } finally {
+          if (prevTest === undefined) delete process.env.UJ_TEST_MODE; else process.env.UJ_TEST_MODE = prevTest;
+          if (prevBuild === undefined) delete process.env.UJ_BUILD_MODE; else process.env.UJ_BUILD_MODE = prevBuild;
+          if (prevServer === undefined) delete process.env.UJ_IS_SERVER; else process.env.UJ_IS_SERVER = prevServer;
+          if (prevNode === undefined) delete process.env.NODE_ENV; else process.env.NODE_ENV = prevNode;
         }
       },
     },

package/dist/utils/attach-log-file.js

@@ -9,18 +9,24 @@
 // Skipped entirely when Manager.isServer() returns true — CI/cloud runs don't need a logs/
 // directory left behind in the workspace.
 //
-// Truncates fresh on each call (flags: 'w'), so a new `npm start` doesn't accumulate stale
+// Truncates fresh on each call (O_TRUNC), so a new `npm start` doesn't accumulate stale
 // lines from the previous run.
 //
-// Idempotent: calling twice with the same path just returns the existing stream.
+// Idempotent: calling twice with the same path just returns the existing fd.
+//
+// Uses synchronous fs.writeSync(fd, ...) rather than createWriteStream(). Reason: gulp tasks
+// crash via thrown errors that propagate to process.exit, and createWriteStream's internal
+// buffer was being dropped before the kernel could flush it — so the very lines describing
+// the crash (the most important ones) never made it to disk. Synchronous writes incur a
+// per-line syscall but guarantee the tail of the log survives an immediate exit.
 
 const fs = require('fs');
 const path = require('path');
 
 const ANSI_PATTERN = /\x1B\[[0-9;]*[a-zA-Z]/g;
 
-let activeStream = null;
-let activePath   = null;
+let activeFd       = null;
+let activePath     = null;
 let originalStdoutWrite = null;
 let originalStderrWrite = null;
 
@@ -33,38 +39,40 @@ function attachLogFile(name) {
 
   const abs = path.resolve(process.cwd(), 'logs', `${name}.log`);
 
-  if (activeStream && activePath === abs) return activeStream;
-  if (activeStream) detach();
+  if (activeFd !== null && activePath === abs) return activeFd;
+  if (activeFd !== null) detach();
 
   fs.mkdirSync(path.dirname(abs), { recursive: true });
-  const stream = fs.createWriteStream(abs, { flags: 'w' });
+  const fd = fs.openSync(abs, 'w');
 
-  stream.write(`# ujm log — ${new Date().toISOString()} — pid=${process.pid}\n`);
+  fs.writeSync(fd, `# ujm log — ${new Date().toISOString()} — pid=${process.pid}\n`);
 
   originalStdoutWrite = process.stdout.write.bind(process.stdout);
   originalStderrWrite = process.stderr.write.bind(process.stderr);
 
   process.stdout.write = function (chunk, ...rest) {
-    try { stream.write(stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+    try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
     return originalStdoutWrite(chunk, ...rest);
   };
   process.stderr.write = function (chunk, ...rest) {
-    try { stream.write(stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+    try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
     return originalStderrWrite(chunk, ...rest);
   };
 
-  activeStream = stream;
-  activePath   = abs;
+  activeFd   = fd;
+  activePath = abs;
 
-  return stream;
+  return fd;
 }
 
 function detach() {
   if (originalStdoutWrite) process.stdout.write = originalStdoutWrite;
   if (originalStderrWrite) process.stderr.write = originalStderrWrite;
-  if (activeStream) activeStream.end();
-  activeStream = null;
-  activePath   = null;
+  if (activeFd !== null) {
+    try { fs.closeSync(activeFd); } catch (e) { /* ignore */ }
+  }
+  activeFd   = null;
+  activePath = null;
   originalStdoutWrite = null;
   originalStderrWrite = null;
 }

package/dist/utils/mode-helpers.js

@@ -2,51 +2,72 @@
 // (build-time `src/build.js`, frontend ES module `src/index.js`, service worker
 // `src/service-worker.js`).
 //
-// Three orthogonal concepts:
-//   isDevelopment() — true when running in dev mode (jekyll dev server, not a
-//                     production build). Detected via NODE_ENV / UJ_BUILD_MODE /
-//                     site config.
-//   isProduction()  — inverse. Running a production-built `_site/`.
-//   isTesting()     — true when UJM's test framework is running this process. Set
-//                     by UJM's test runners (UJ_TEST_MODE=true) and consumer test
-//                     setups that want the same signal.
+// `getEnvironment()` is the SINGLE SOURCE OF TRUTH: it is the ONLY function that reads the
+// raw signals (UJ_TEST_MODE / window.Configuration.uj.environment / UJ_BUILD_MODE /
+// UJ_IS_SERVER / NODE_ENV) and resolves them to exactly ONE of three mutually-exclusive
+// values. The three is*() checks DERIVE from it — they never read raw signals themselves,
+// so they can never disagree with getEnvironment().
 //
-// Use these whenever behavior should differ by *what kind of process* you're in —
-// shorter timeouts in tests, prompts suppressed in tests, dev-only banners.
-// Don't use them for "should we hit dev or prod backends" — that's a config
-// concern; use `getEnvironment()` for that (in build.js).
+//   isDevelopment() — `getEnvironment() === 'development'`: running in dev mode (jekyll dev
+//                     server, not a production build), and NOT testing.
+//   isTesting()     — `getEnvironment() === 'testing'`: UJM's test framework is running this
+//                     process (UJ_TEST_MODE=true). TAKES PRECEDENCE — a test run is not dev.
+//   isProduction()  — `getEnvironment() === 'production'`: running a production-built `_site/`,
+//                     and NOT testing. A real positive check — NOT `!isDevelopment()`.
 //
-// Context caveat: in build-time Node (gulp / CLI), `window` is undefined. We
-// detect via `typeof window` so the same code works in every context. In test
-// mode the browser-side check is short-circuited via UJ_TEST_MODE / global so
-// `isTesting()` returns a stable value regardless of which test layer is running.
+// To gate "anything non-production" use `!isProduction()` or `isDevelopment() ||
+// isTesting()` intentionally — never assume two values.
+//
+// Context caveat: in build-time Node (gulp / CLI), `window` is undefined. getEnvironment()
+// detects via `typeof window` so the same code works in every context. Browser detection
+// reads `window.Configuration.uj.environment` (baked into the page at build time).
 
-function isDevelopment() {
-  // Build-time Node fallback.
+// getEnvironment() — the SINGLE SOURCE OF TRUTH. Reads every raw signal and resolves to
+// exactly ONE of 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
+// Precedence: testing → production → development.
+function getEnvironment() {
+  // 1. Testing wins — set by UJM's test runners / harness, or a testing-baked build.
+  //    Works in Node (process.env), browser (globalThis set before consumer JS), and
+  //    config-baked builds (window.Configuration.uj.environment === 'testing').
+  if (typeof process !== 'undefined' && process.env && process.env.UJ_TEST_MODE === 'true') return 'testing';
+  if (typeof globalThis !== 'undefined' && globalThis.UJ_TEST_MODE === true) return 'testing';
+  if (typeof window !== 'undefined' && window.Configuration && window.Configuration.uj
+    && window.Configuration.uj.environment === 'testing') return 'testing';
+
+  // 2. Build-time Node signals (a production build or the running dev server).
   if (typeof process !== 'undefined' && process.env) {
-    if (process.env.UJ_BUILD_MODE === 'true') return false;
-    if (process.env.NODE_ENV === 'development') return true;
-    if (process.env.UJ_IS_SERVER === 'true') return false;
+    if (process.env.UJ_BUILD_MODE === 'true') return 'production';
+    if (process.env.UJ_IS_SERVER === 'true') return 'production';
+    if (process.env.NODE_ENV === 'development') return 'development';
   }
-  // Browser-side: look at window.Configuration if present.
+
+  // 3. Browser-side: the environment baked into the page at build time.
   if (typeof window !== 'undefined' && window.Configuration && window.Configuration.uj) {
-    if (window.Configuration.uj.environment === 'development') return true;
-    if (window.Configuration.uj.environment === 'production') return false;
+    if (window.Configuration.uj.environment === 'development') return 'development';
+    if (window.Configuration.uj.environment === 'production') return 'production';
   }
-  return false;
+
+  // 4. Default: development. UJM's deployed artifacts ALWAYS carry their signal — the
+  //    browser has `window.Configuration.uj.environment` baked in, and build-time Node
+  //    always sets UJ_BUILD_MODE / UJ_IS_SERVER. So reaching here means a bare tooling /
+  //    local-script context, where development is the sensible answer. (Contrast BEM/EM,
+  //    whose deployed RUNTIME can legitimately lack a signal, so they default to production.)
+  return 'development';
+}
+
+// The three checks DERIVE from getEnvironment() — they never read raw signals, so they can
+// never disagree with it. isDevelopment() is NOT true in testing; isProduction() is a real
+// positive check (never `!isDevelopment()`).
+function isDevelopment() {
+  return getEnvironment() === 'development';
 }
 
 function isProduction() {
-  return !this.isDevelopment();
+  return getEnvironment() === 'production';
 }
 
 function isTesting() {
-  // Canonical signal — set by UJM's test runners and consumer test setups alike.
-  // Works in Node (process.env) AND in browser contexts (the harness preload sets
-  // globalThis.UJ_TEST_MODE before any consumer code runs).
-  if (typeof process !== 'undefined' && process.env && process.env.UJ_TEST_MODE === 'true') return true;
-  if (typeof globalThis !== 'undefined' && globalThis.UJ_TEST_MODE === true) return true;
-  return false;
+  return getEnvironment() === 'testing';
 }
 
 // `getVersion()` — returns UJM's own version string.
@@ -64,19 +85,23 @@ function getVersion() {
 
 // Mix the helpers into a Manager constructor's prototype + the constructor itself
 // (so `Manager.isTesting()` works statically too, matching BEM/EM/BXM pattern).
+// getEnvironment() is the SSOT and is attached here too — build.js no longer defines it.
 function attachTo(Manager) {
-  Manager.prototype.isDevelopment = isDevelopment;
-  Manager.prototype.isProduction  = isProduction;
-  Manager.prototype.isTesting     = isTesting;
-  Manager.prototype.getVersion    = getVersion;
-  Manager.isDevelopment = isDevelopment;
-  Manager.isProduction  = isProduction;
-  Manager.isTesting     = isTesting;
-  Manager.getVersion    = getVersion;
+  Manager.prototype.getEnvironment = getEnvironment;
+  Manager.prototype.isDevelopment  = isDevelopment;
+  Manager.prototype.isProduction   = isProduction;
+  Manager.prototype.isTesting      = isTesting;
+  Manager.prototype.getVersion     = getVersion;
+  Manager.getEnvironment = getEnvironment;
+  Manager.isDevelopment  = isDevelopment;
+  Manager.isProduction   = isProduction;
+  Manager.isTesting      = isTesting;
+  Manager.getVersion     = getVersion;
 }
 
 module.exports = {
   attachTo,
+  getEnvironment,
   isDevelopment,
   isProduction,
   isTesting,

package/docs/assets.md

@@ -2,6 +2,11 @@
 
 This document covers UJM's asset layout, consuming-project overrides, the JSON-driven section configuration system (nav, footer, account dropdown), frontmatter-driven page customization, webpack aliases, and the page module pattern.
 
+> **Authoring or selecting a theme?** The `themes/[theme-id]/` layout/include
+> paths and the `__theme__` SCSS/JS resolution referenced throughout this doc are
+> explained in full — including the classy layout fallback and how to build a new
+> theme — in [docs/themes.md](themes.md).
+
 ## Ultimate Jekyll Manager Files (THIS project)
 
 **CSS:**
@@ -269,7 +274,7 @@ import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js
 import(`__project_assets__/js/pages/${pageModulePath}`)
 ```
 
-**How they work together:** `src/index.js` loads page modules from both aliases — first from `__main_assets__` (UJM defaults), then from `__project_assets__` (project overrides/extensions). If a project module doesn't exist, it gracefully skips. This enables a layered system where UJM provides defaults and consuming projects can extend or override page behavior.
+**How they work together:** `src/index.js` loads page modules from **three** layers, executed in order: `__main_assets__` (UJM default) → `__theme__/pages/...` (active theme) → `__project_assets__` (consumer override/extension). A missing module at any layer gracefully skips. This layered system mirrors the page-CSS cascade — UJM provides defaults, the theme customizes, and the consuming project always gets the final say. See [docs/themes.md → Page-specific JS](themes.md#5-page-specific-js-theme-aware-additive--mirrors-page-css).
 
 **When to use which:**
 - **`__main_assets__`** — When importing UJM-provided libraries, core modules, or referencing UJM's built-in page scripts

package/docs/environment-detection.md

@@ -0,0 +1,85 @@
+# Environment Detection
+
+`getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
+
+```javascript
+Manager.getEnvironment()    // 'development' | 'testing' | 'production'
+
+Manager.isDevelopment()     // true ONLY in development
+Manager.isTesting()         // true ONLY in testing
+Manager.isProduction()      // true ONLY in production
+```
+
+**The Manager is the single source of truth.** `getEnvironment()` is the ONLY function that reads the raw signals (`UJ_TEST_MODE` / `window.Configuration.uj.environment` / `UJ_BUILD_MODE` / `UJ_IS_SERVER` / `NODE_ENV`). The three `is*()` checks **derive** from it live on every call — they never read raw signals themselves, so they can never disagree with `getEnvironment()`.
+
+**One implementation, mixed into every Manager.** UJM mixes the helpers into the build-time Manager and the frontend Manager via `attachTo(Manager)` from [src/utils/mode-helpers.js](../src/utils/mode-helpers.js), available as both prototype methods (`manager.isTesting()`) and statics (`Manager.isTesting()`).
+
+```javascript
+manager.getEnvironment()    // same answer build-time and in the browser
+Manager.isTesting()         // static form, for build-time scripts
+```
+
+**Resolution order:** testing wins first, then production, else development. The three checks are mutually exclusive — exactly one is true. `isDevelopment()` is **false** during testing, and `isProduction()` is a real positive check (it is NOT `!isDevelopment()`).
+
+## Available helpers
+
+| Helper | Returns |
+|---|---|
+| `getEnvironment()` | `'development' \| 'testing' \| 'production'` — the SSOT resolver; the only reader of raw signals. |
+| `isDevelopment()` | `true` ONLY in development (jekyll dev server, not a production build), and NOT testing. Derives from `getEnvironment()`. |
+| `isTesting()` | `true` ONLY in testing (`UJ_TEST_MODE === 'true'`). **Takes precedence** — a test run is not development. |
+| `isProduction()` | `true` ONLY in production (a production-built `_site/`). A **real positive check** — NOT `!isDevelopment()`. |
+
+## Gating side effects — use the INTENTIONAL check
+
+Because there are three environments, never gate a side effect on a two-value assumption. State what you mean:
+
+```javascript
+// Production-only (skip real telemetry / production behavior in dev AND testing):
+if (isProduction())  { /* do the real thing */ }
+if (!isProduction()) { /* skip / use the safe local behavior */ }
+
+// Local-or-test (anything that should run in BOTH dev and testing):
+if (isDevelopment() || isTesting()) { /* localhost URL, observable redirect delay, dev banners */ }
+```
+
+**Avoid** `if (!isDevelopment())` or `if (env !== 'development')` to gate production behavior — those wrongly include `testing` as production and leak real side effects during test runs. This is the bug class that motivated the 3-value model.
+
+## URL helpers
+
+UJM does **not** own backend URL helpers. Frontend page code resolves backend URLs through the `web-manager` runtime singleton:
+
+```javascript
+webManager.getApiUrl()  // the brand's API URL — from web-manager, not UJM
+```
+
+`web-manager`'s `getApiUrl()` follows the same convention as the sister frameworks — local in development/testing, production otherwise — so the rule "call the getter, never hardcode" still applies; the implementation just lives in `web-manager`. UJM's own URL helper is build-time only: `Manager.getWorkingUrl()` returns the BrowserSync dev-server URL (or the configured project URL) for the running dev server.
+
+## Where they live
+
+Source: [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) for `getEnvironment()` + `is*()` + `getVersion()`. The module exposes the functions plus an `attachTo(Manager)` mixin. Attached at the bottom of the build-time Manager [src/build.js](../src/build.js) and the frontend Manager [src/index.js](../src/index.js) — so build-time scripts and browser code resolve the environment identically.
+
+## How detection works
+
+`getEnvironment()` resolves in this precedence order:
+
+1. **Testing** — `process.env.UJ_TEST_MODE === 'true'`, `globalThis.UJ_TEST_MODE === true`, or a build baked with `window.Configuration.uj.environment === 'testing'` (set by the harness before any consumer JS runs). A test run is a test run regardless of any other signal.
+2. **Build-time signals** — `UJ_BUILD_MODE === 'true'` → production; `UJ_IS_SERVER === 'true'` → production; `NODE_ENV === 'development'` → development.
+3. **Browser signal** — `window.Configuration.uj.environment` (`'development'` / `'production'`), baked into the page at build time.
+4. **Default** — development. UJM's deployed artifacts always carry their signal (the browser has `window.Configuration.uj.environment` baked in; build-time Node always sets `UJ_BUILD_MODE`/`UJ_IS_SERVER`), so reaching here means a bare tooling / local-script context where development is correct. (Contrast BEM/EM, whose deployed *runtime* can legitimately lack a signal, so they default to **production**.)
+
+## Adding a new helper
+
+Write the function in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) (or a new `src/utils/<topic>-helpers.js` module), expose it from `attachTo(Manager)`, and ensure both the build-time and frontend Managers call `attachTo`. For anything environment-derived, derive from `getEnvironment()` rather than reading `process.env` / `window.Configuration` directly, so there is one source of truth and no chance of drift.
+
+## Why this matters
+
+**One signal, used everywhere.** The test runner sets `UJ_TEST_MODE=true`; every piece of code that calls `isTesting()` (framework or consumer) then sees `true` — no need to invent a per-module env var.
+
+**Sub-modules check the same signal.** When framework code (a network probe, a prompt) needs to skip side effects in tests, it checks `isTesting()` — the same answer the consumer's own code gets. No drift.
+
+**`is*()` can never disagree with `getEnvironment()`.** Because the checks derive from the single resolver instead of reading raw signals (`window.Configuration` vs `UJ_BUILD_MODE`), there is exactly one definition of "what environment is this," and a wrong-but-confident gate is structurally impossible.
+
+## See also
+
+- [test-framework.md](test-framework.md) — `UJ_TEST_MODE` is set automatically by the test runners; `--integration` gates real external APIs.

package/docs/test-framework.md

@@ -2,6 +2,28 @@
 
 UJM ships a built-in three-layer test harness. `npx mgr test` discovers framework suites from `<ujm>/dist/test/suites/**/*.js` and consumer suites from `<cwd>/test/**/*.js`, partitions by `layer`, and runs each layer in the right environment. Same shape as the sister harnesses in EM (electron-manager) and BXM (browser-extension-manager).
 
+## 🚫 NEVER mock — test against the real harness (HARD RULE)
+
+**Do NOT hand-roll fake/stub/mock objects.** Every test runs against a real environment, and the harness hands the test the real thing — use it:
+
+- **`build` layer** gets the **real** `Manager` from `require('ultimate-jekyll-manager/build')` — call its real API (`getConfig`, `getUJMConfig`, `getPackage`, `isTesting`, the gulp pure helpers). Never fake a `Manager` whose `getConfig()` returns canned data.
+- **`page` layer** runs in a **real** headless Chromium tab with real `window`/`document` and the harness-provided `window.Configuration`. Drive the real frontend Manager surface; don't stub DOM globals in your test.
+- **`boot` layer** runs against the **real** built `_site/` served over a **real** HTTP origin — exercise the actually-shipped site through Puppeteer.
+- **Pure functions (zero I/O) are the ONLY thing you call directly** — e.g. `mergeJekyllConfigs`, `validateYAMLFrontMatter`, `createTemplateTransform`, `collectTextNodes`. `require()` them and pass plain inputs. That is NOT mocking — there is nothing to mock. The moment a function touches real I/O (config files, the DOM, the HTTP server, an external API), it MUST run against the real harness/build, not a stub.
+
+If you find yourself writing `const mockX = {...}` to satisfy code under test, STOP — use the real context the layer already provides, or (if it's genuinely pure) call it with plain data.
+
+### The ONLY two exceptions where a narrow stub is allowed
+
+Mock **nothing** by default. There are exactly two cases where the real dependency genuinely cannot run in the test environment — and even then, stub the *smallest possible seam* (one method / one object), restore it immediately, and comment *why*:
+
+1. **A side effect that would destroy the test run itself.** If the real call would kill or corrupt the harness — a process-exit, a destructive `_site/` wipe, a recursive re-invocation of the build/test command — stub *that one call* to a no-op, assert the surrounding logic, then restore. You are preventing the harness from terminating mid-assertion, not faking behavior.
+2. **A real dependency the test environment can't provide.** When the real thing only exists from infra you can't stand up in the current layer (an external service with no local equivalent, a second running instance), a unit test may hand minimal inputs to exercise the logic in isolation — but a real-harness test (`page`/`boot`) MUST still cover the wired path where one exists.
+
+If you can run it for real, you must. These exceptions are not a license to unit-test in isolation when a real-harness layer would work.
+
+**External APIs are skipped in-source, NOT mocked.** UJM build/gulp code that would hit the network (e.g. fetching Firebase auth files) short-circuits in its own source when `Manager.isTesting()` is true — it returns early, it does not return canned/mocked data. See [environment-detection.md](environment-detection.md). If a suite has slower live-integration tests, gate them behind the `--integration` flag (`UJ_TEST_INTEGRATION=1`) and run the real path; anything such a test creates externally MUST be cleaned up by the test (`cleanup`/`inspect` teardown) — the runner does not clean external systems.
+
 ## Quick start
 
 ```bash
@@ -135,7 +157,7 @@ The public surface exposed by `require('ultimate-jekyll-manager/build')` include
 - `Manager.logger(name)` — returns a `Logger` instance
 - `Manager.require(path)` — escape hatch when you really need a UJM transitive dep
 
-See [docs/cross-context-helpers.md](cross-context-helpers.md) for `isTesting`/`isDevelopment` semantics.
+See [docs/environment-detection.md](environment-detection.md) for `isTesting`/`isDevelopment` semantics.
 
 ## Reporter contract — `__UJM_TEST__` JSON-line events
 
@@ -162,12 +184,35 @@ Same protocol as EM (`__EM_TEST__`) and BXM (`__BXM_TEST__`). One marker per fra
 - **Excluded**: any directory starting with `_` (handy for shared helpers).
 - **Framework boot suites** are excluded when the cwd's `package.json#name` is not `ultimate-jekyll-manager` — they target UJM's fixture site, not the consumer's. Consumers write their own boot tests in `<cwd>/test/boot/`.
 
+## `test/_init.js` — pre-test lifecycle hook
+
+The runner loads an optional `test/_init.js` from **both** test roots — the framework (`<UJM>/test/_init.js`) and the consumer project (`<cwd>/test/_init.js`) — and runs it **once, before any suite** (it is NOT itself run as a test; the `_`-prefix keeps it out of discovery). Mirrors the same hook in BEM/EM/BXM so all four frameworks share one shape.
+
+The module **must export a function** — `module.exports = (ctx) => ({ ... })` — called with `{ projectRoot }` and returning the hook object. It may declare:
+
+- `async setup({ projectRoot })` — runs once before the suites, e.g. to scaffold a fixture file the boot layer needs.
+
+There is **no `cleanup` hook** and **no `accounts` field** (unlike BEM — these frameworks have no auth/user system): tests clean up after themselves, so there is nothing project-level to tear down.
+
+```javascript
+// <cwd>/test/_init.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = ({ projectRoot }) => ({
+  async setup() {
+    // Seed any fixture a suite needs before it runs.
+    fs.mkdirSync(path.join(projectRoot, '.temp'), { recursive: true });
+  },
+});
+```
+
 ## Env vars
 
 | Env | Set by | Purpose |
 |---|---|---|
 | `UJ_TEST_MODE=true`         | `npx mgr test` always | Canonical test signal. `Manager.isTesting()` reads this. Use it to short-circuit network calls / prompts / long timers in code that runs during tests. |
-| `UJ_TEST_INTEGRATION=1`     | `--integration` flag | Opt-in flag for slower integration tests if your suite has them |
+| `UJ_TEST_INTEGRATION=1`     | `--integration` flag | Opt-in flag for slower live-integration tests if your suite has them. These run the **real** external path (NOT mocked); anything they create externally MUST be cleaned up by the test. |
 | `UJ_TEST_BOOT_PROJECT`      | Auto-set when UJM tests itself; else manual | Project root the boot runner uses (its `_site/` is the boot target) |
 | `UJ_TEST_BOOT_DIR`          | Manual | Absolute override for the `_site/` directory. Wins over `UJ_TEST_BOOT_PROJECT/_site` and `<cwd>/_site` |
 | `UJ_TEST_DEBUG=1`           | Manual | Verbose Puppeteer console output piped to the parent stdout |
@@ -179,5 +224,5 @@ Puppeteer is a `devDependency` of UJM itself. Consumers don't get it unless they
 ## See also
 
 - [test-boot-layer.md](test-boot-layer.md) — deep dive on boot layer (`_site/` discovery, HTTP server, fixture vs consumer)
-- [cross-context-helpers.md](cross-context-helpers.md) — `Manager.isTesting()` / `isDevelopment()` semantics
+- [environment-detection.md](environment-detection.md) — `Manager.isTesting()` / `isDevelopment()` semantics
 - [cli.md](cli.md) — CLI surface, env-var conventions