ultimate-jekyll-manager 1.1.10 → 1.2.0

package/docs/cross-context-helpers.md

@@ -0,0 +1,75 @@
+# Cross-context Helpers
+
+`src/utils/mode-helpers.js` exposes four shared helpers mixed into every UJM Manager via `attachTo(Manager)`. Mirrors the same pattern in EM and BXM. Used when behavior should differ by *what kind of process* you're in — short-circuit network probes in tests, suppress dev-only banners in production, etc.
+
+## API
+
+| Method | Returns | Purpose |
+|---|---|---|
+| `Manager.isTesting()` | `boolean` | True when UJM's test framework is running this process. Set by `npx mgr test` (`UJ_TEST_MODE=true`) and consumer test setups that want the same signal. |
+| `Manager.isDevelopment()` | `boolean` | True when running in dev mode (not a production build). Reads `UJ_BUILD_MODE` / `NODE_ENV` / `UJ_IS_SERVER` / `window.Configuration.uj.environment` depending on context. |
+| `Manager.isProduction()` | `boolean` | Inverse of `isDevelopment()`. |
+| `Manager.getVersion()` | `string \| null` | UJM's version from `<cwd>/package.json#version`. Null if no `package.json` (e.g. shipped browser bundle). |
+
+All four are available both **statically** on the Manager constructor and on **`Manager.prototype`**, so these all work:
+
+```js
+const Manager = require('ultimate-jekyll-manager/build');
+Manager.isTesting();                  // static
+new Manager().isTesting();            // instance
+```
+
+## When to use
+
+```js
+// In a build helper that fetches Firebase auth files:
+async function fetchFirebaseAuthFiles() {
+  if (Manager.isTesting()) {
+    return;  // short-circuit — tests provide their own stubs
+  }
+  // ...real fetch
+}
+
+// In a gulp task that opens the dev browser:
+function maybeOpenBrowser() {
+  if (Manager.isBuildMode() || Manager.isTesting()) return;
+  // ...exec `open` etc.
+}
+
+// In a frontend module that logs verbose debug info:
+if (manager.isDevelopment()) {
+  console.log('[dev] webManager loaded with', cfg);
+}
+```
+
+**Don't use these for "should I hit dev or prod backends"** — that's a config concern. Use `Manager.getEnvironment()` (returns `'development'` or `'production'` strings) for that distinction.
+
+## How `isDevelopment` is detected
+
+Order of checks:
+
+1. **Build-time Node**: `process.env.UJ_BUILD_MODE === 'true'` → production. `process.env.NODE_ENV === 'development'` → development. `process.env.UJ_IS_SERVER === 'true'` → production.
+2. **Browser**: `window.Configuration.uj.environment` if present (`'development'` or `'production'`).
+3. Default → `false`.
+
+## How `isTesting` is detected
+
+Two checks (either is sufficient):
+
+1. **Node**: `process.env.UJ_TEST_MODE === 'true'`. Set automatically by `npx mgr test`.
+2. **Browser**: `globalThis.UJ_TEST_MODE === true`. Set automatically by UJM's `page`-layer harness HTML before any consumer code runs.
+
+This means consumer code that calls `Manager.isTesting()` from a tab context gets the right answer — Node-only check would always return false in a browser.
+
+## Adding new helpers
+
+If you find yourself writing the same `if (process.env.UJ_FOO === 'true') ...` check more than twice, factor it into `mode-helpers.js`. Things to consider:
+
+- Does the helper need to work in **all** contexts (Node build-time + browser page + service worker)? If yes, gate every check with `typeof process !== 'undefined'` / `typeof window !== 'undefined'` so the same code runs everywhere.
+- Should it be mixed into static AND prototype? Almost always yes — the static form is for build-time CLI usage, the instance form for runtime use.
+- Add a test in `src/test/suites/build/mode-helpers.test.js` that toggles the underlying env var and asserts both states.
+
+## See also
+
+- [test-framework.md](test-framework.md) — the test harness that sets `UJ_TEST_MODE`
+- [cli.md](cli.md) — full env-var matrix

package/docs/test-boot-layer.md

@@ -0,0 +1,110 @@
+# Boot Layer
+
+The boot layer runs Puppeteer against a real built `_site/` served by a tiny embedded HTTP server. It's the integration smoke that catches "did my actually-shipped site boot?" regressions — things plain-Node build tests can't see.
+
+## Why a real HTTP server (not `file://`)
+
+Service workers refuse to register from `file://` URLs. Since SW registration / activation / cache-name composition is a key boot signal, the harness spins up a zero-dep HTTP server (`src/test/server.js`, ~100 lines of pure Node `http`) on an ephemeral loopback port and points Puppeteer at it.
+
+The server also serves files with correct MIME types (text/html / text/javascript / text/css / application/json / image/png / etc.) and sets `Service-Worker-Allowed: /` so consumers can register a SW from any subdirectory.
+
+## `_site/` discovery order
+
+The runner picks the first of these that has an `index.html`:
+
+1. `UJ_TEST_BOOT_DIR` — absolute path. Full override. Useful when your build pipeline writes elsewhere (`build/`, `public/`, custom dirs).
+2. `UJ_TEST_BOOT_PROJECT/_site` — auto-set when UJM tests itself; points at the fixture site under `src/test/fixtures/consumer-site/`. Consumers can set this manually if they want to run boot tests against a sibling project.
+3. `<cwd>/_site` — the default for UJM consumers. After `npm run build`, Jekyll writes here.
+
+If none match, boot tests are reported as skipped with a clear "run `npm run build` first" message.
+
+## Fixture site vs consumer site
+
+UJM's own framework boot suites assert against a fixture `_site/` at `src/test/fixtures/consumer-site/_site/`. The fixture is hand-built (no real Jekyll run needed during framework self-tests) and contains the minimum surface needed to verify boot:
+
+- `index.html` — renders title + h1
+- `about.html` — proves Jekyll-style `/about` → `/about.html` suffix fallback works
+- `service-worker.js` — registers + activates + responds to `get-cache-name` postMessage
+- `build.json` — proves UJM-generated metadata is served as application/json
+- `assets/css/main.bundle.css`, `assets/js/main.bundle.js` — prove MIME routing
+
+When a real consumer runs `npx mgr test`, framework boot suites are **excluded** (their assertions reference fixture-only content like "UJM Fixture Consumer"). Consumers write their own boot tests under `test/boot/` against their real `_site/`.
+
+## Single-Chromium-instance amortization
+
+All boot tests run inside one Puppeteer browser instance. Per-test cost: ~150ms for the page navigation + assertions. Browser startup (~1s) is paid once per `npx mgr test --layer boot` invocation, not once per test.
+
+## What to assert
+
+Good boot-test targets (high-signal, low-flake):
+
+| Assertion | Why it matters |
+|---|---|
+| Home page has expected title / h1 | Catches "template variable didn't resolve" + "Liquid build failed" silently |
+| `/some-route` resolves with 200 | Catches Jekyll permalink regressions + suffix-fallback edge cases |
+| `build.json` is present + parses + has expected `config.brand.id` | Catches `gulp/build-config` regressions where the runtime config injection broke |
+| `service-worker.js` MIME is `text/javascript` | A `text/html` MIME means the SW route is wrong; SW registration silently fails |
+| SW reaches `activated` state | Catches "skipWaiting / clients.claim never wired" |
+| SW responds to a postMessage with expected cache name | Catches "UJ_BUILD_JSON injection broken" or "cache-name composition regressed" |
+| No `console.error` events fire during page load | Catches broken bundles, malformed `window.Configuration`, webManager init crashes |
+
+Avoid (high-flake):
+
+- "Wait for a specific element to be visible" without `waitForSelector` — pages render asynchronously
+- Animation-dependent assertions (CSS transition completes, etc.) — timing-sensitive
+- Anything that hits production Firebase / external APIs — boot tests should be hermetic
+
+## Example consumer boot test
+
+From Chatsy's `test/boot/site.test.js`:
+
+```js
+module.exports = {
+  layer: 'boot',
+  description: 'Chatsy _site/ loads + SW registers',
+  type: 'group',
+  tests: [
+    {
+      description: 'home renders with title',
+      inspect: async ({ site, page, expect }) => {
+        const res = await page.goto(site.baseUrl + '/', { waitUntil: 'domcontentloaded' });
+        expect(res.status()).toBe(200);
+        expect((await page.title()).length).toBeGreaterThan(0);
+      },
+    },
+    {
+      description: 'service-worker.js has javascript content type',
+      inspect: async ({ site, page, expect }) => {
+        const res = await page.goto(site.baseUrl + '/service-worker.js');
+        expect(/(text|application)\/javascript/.test(res.headers()['content-type'])).toBe(true);
+      },
+    },
+  ],
+};
+```
+
+## Build-then-test pattern
+
+For local development:
+
+```bash
+npm run build          # gulp pipeline produces _site/
+npx mgr test --layer boot
+```
+
+For CI: do the same. Don't try to share `_site/` between machines — Jekyll's incremental cache makes that brittle. Always build, then test.
+
+## Debugging
+
+Set `UJ_TEST_DEBUG=1` to see Puppeteer's console output piped to your terminal:
+
+```bash
+UJ_TEST_DEBUG=1 npx mgr test --layer boot
+```
+
+Useful when a boot test fails with an opaque error — you'll see the actual `console.error` that triggered the failure plus any other tab-side logging.
+
+## See also
+
+- [test-framework.md](test-framework.md) — overall harness reference
+- [build-system.md](build-system.md) — the gulp pipeline that produces `_site/`

package/docs/test-framework.md

@@ -0,0 +1,183 @@
+# Test Framework
+
+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).
+
+## Quick start
+
+```bash
+npx mgr test                   # all layers
+npx mgr test --layer build     # plain Node, fast
+npx mgr test --layer page      # headless Chromium tab against harness HTML
+npx mgr test --layer boot      # headless Chromium against built _site/
+npx mgr test --filter foo      # filter tests by name substring
+npx mgr test --reporter json   # machine-readable __UJM_TEST__ events
+```
+
+`npm test` works too — added to consumer `package.json#scripts.test` on `npx mgr setup`.
+
+## Layers
+
+| Layer | Runs in | Use for |
+|---|---|---|
+| `build` | Plain Node, ~ms | `Manager.getConfig/getPackage/getUJMConfig`, CLI alias resolution, gulp pure helpers (`mergeJekyllConfigs`, `validateYAMLFrontMatter`, `createTemplateTransform`, `collectTextNodes`), mode-helpers env gating, templating brackets |
+| `page` | Headless Chromium tab via Puppeteer | Frontend Manager lifecycle, `window.Configuration` plumbing, DOM assertions, prerendered icons template, anything that needs real `window`/`document` |
+| `boot` | Headless Chromium loading the consumer's built `_site/` via a tiny local HTTP server | End-to-end smoke: site builds + serves, pages render, service worker registers + activates + responds, no console errors |
+
+There is no `main`/`background` layer (EM/BXM have those because they own long-running runtime processes; UJM does not).
+
+## Writing a test
+
+Every test file is a CommonJS module exporting one of three forms:
+
+```js
+// Standalone
+module.exports = {
+  layer: 'build',
+  description: 'config has brand.id',
+  timeout: 5000,
+  run: async (ctx) => {
+    const Manager = require('ultimate-jekyll-manager/build');
+    const cfg = Manager.getConfig('project');
+    ctx.expect(cfg.brand.id).toBeTruthy();
+  },
+  cleanup: async (ctx) => { /* optional */ },
+};
+
+// Suite — sequential, stops on first failure, shares `ctx.state`
+module.exports = {
+  type: 'suite',
+  layer: 'build',
+  description: 'config flow',
+  tests: [
+    { name: 'load',  run: async (ctx) => { ctx.state.cfg = Manager.getConfig('project'); } },
+    { name: 'check', run: async (ctx) => { ctx.expect(ctx.state.cfg.brand.id).toBe('foo'); } },
+  ],
+};
+
+// Group — runs ALL tests even if some fail
+module.exports = {
+  type: 'group',
+  layer: 'build',
+  tests: [ /* ... */ ],
+};
+
+// Array form → implicit group
+module.exports = [
+  { name: 'a', run: async (ctx) => { /* ... */ } },
+  { name: 'b', run: async (ctx) => { /* ... */ } },
+];
+```
+
+### The `ctx` (test context)
+
+Every `run(ctx)` and `cleanup(ctx)` callback receives:
+
+| Property | Description |
+|---|---|
+| `ctx.expect`     | Jest-compatible assertion (`toBe`, `toEqual`, `toBeTruthy`, `toContain`, `toMatch`, `toThrow`, `toBeGreaterThan`, etc. + `.not.` negation) |
+| `ctx.state`      | Plain object shared across tests in a suite/group |
+| `ctx.layer`      | Current layer name |
+| `ctx.skip(reason)` | Throws SkipError — the runner records as skipped |
+
+### Boot-layer test shape
+
+Boot tests use `inspect` instead of `run`. The callback receives `{ site, page, expect, projectRoot }`:
+
+```js
+module.exports = {
+  layer: 'boot',
+  description: 'home renders + SW registers',
+  timeout: 15000,
+  inspect: async ({ site, page, expect, projectRoot }) => {
+    const res = await page.goto(site.baseUrl + '/');
+    expect(res.status()).toBe(200);
+    expect(await page.title()).toBeTruthy();
+  },
+};
+```
+
+| Property | Description |
+|---|---|
+| `site.baseUrl`    | `http://127.0.0.1:<port>` — the harness HTTP server root |
+| `site.port`       | Ephemeral port the local server bound to |
+| `site.root`       | Absolute path to the served `_site/` |
+| `page`            | Puppeteer Page (fresh per test) |
+| `expect`          | Same Jest-compatible matchers |
+| `projectRoot`     | Absolute path to the consumer project |
+
+## Consumer pattern — use the public Manager API
+
+When writing consumer tests, **use the public Manager API** — don't reach into UJM's transitive deps:
+
+```js
+// Good — uses the public API
+const Manager = require('ultimate-jekyll-manager/build');
+const cfg = Manager.getUJMConfig();
+const pkg = Manager.getPackage('project');
+
+// Bad — reaches into UJM's transitive deps. Brittle: if UJM swaps json5 for
+// jsonc-parser, your test breaks even though UJM's public API hasn't changed.
+const json5 = require('json5');
+const fs = require('fs');
+const cfg = json5.parse(fs.readFileSync('config/ultimate-jekyll-manager.json', 'utf8'));
+```
+
+The public surface exposed by `require('ultimate-jekyll-manager/build')` includes:
+
+- `Manager.getConfig(type)` — reads `_config.yml` (type: `'project'` or `'main'`)
+- `Manager.getPackage(type)` — reads `package.json` (type: `'project'` or `'main'`)
+- `Manager.getUJMConfig()` — reads `config/ultimate-jekyll-manager.json` (JSON5)
+- `Manager.getRootPath(type)` — project cwd or UJM package root
+- `Manager.getEnvironment()` — `'development'` or `'production'`
+- `Manager.isBuildMode()` / `isQuickMode()` / `isServer()` / `actLikeProduction()`
+- `Manager.isTesting()` / `isDevelopment()` / `isProduction()` / `getVersion()` (from `mode-helpers.js`)
+- `Manager.getMemoryUsage()` / `Manager.logMemory(logger, label)` / `Manager.processBatches(items, size, fn, logger)`
+- `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.
+
+## Reporter contract — `__UJM_TEST__` JSON-line events
+
+`--reporter json` emits one JSON line per event for external tools (CI dashboards, IDE plugins):
+
+```
+__UJM_TEST__{"event":"result","name":"my-test","passed":true,"duration":12}
+__UJM_TEST__{"event":"result","name":"other-test","passed":false,"duration":34,"error":"expected 1 to be 2"}
+__UJM_TEST__{"event":"skip","name":"x","reason":"manual"}
+```
+
+Then a final summary line:
+
+```json
+{"event":"summary","passed":42,"failed":1,"skipped":0,"total":43}
+```
+
+Same protocol as EM (`__EM_TEST__`) and BXM (`__BXM_TEST__`). One marker per framework; same JSON shape.
+
+## Discovery
+
+- **Framework suites**: glob `<ujm>/dist/test/suites/**/*.js` (resolved from `__dirname/suites` in `runner.js`).
+- **Consumer suites**: glob `<cwd>/test/**/*.js`.
+- **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/`.
+
+## 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_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 |
+
+## Puppeteer as a peer-optional dep
+
+Puppeteer is a `devDependency` of UJM itself. Consumers don't get it unless they write `page` or `boot` tests. If a consumer tries to run `page`/`boot` tests without puppeteer installed, those layers report as skipped with a clear message — build-layer tests still run.
+
+## 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
+- [cli.md](cli.md) — CLI surface, env-var conventions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate-jekyll-manager",
-  "version": "1.1.10",
+  "version": "1.2.0",
   "description": "Ultimate Jekyll dependency manager",
   "main": "dist/index.js",
   "exports": {
@@ -13,7 +13,8 @@
     "prepare": "node -e \"require('prepare-package')()\"",
     "prepare:watch": "node -e \"require('prepare-package/watch')()\"",
     "wm:prod": "npm uninstall web-manager && npm i web-manager@latest",
-    "wm:local": "npm uninstall web-manager && npm i ../web-manager"
+    "wm:local": "npm uninstall web-manager && npm i ../web-manager",
+    "test": "node ./bin/ultimate-jekyll test"
   },
   "bin": {
     "uj": "bin/ultimate-jekyll",
@@ -32,7 +33,8 @@
     "start": "npx mgr clean && npx mgr setup && bundle exec npm run gulp --",
     "gulp": "gulp --cwd ./ --gulpfile ./node_modules/ultimate-jekyll-manager/dist/gulp/main.js",
     "build": "npx mgr clean && npx mgr setup && UJ_BUILD_MODE=true bundle exec npm run gulp -- build",
-    "deploy": "npx mgr deploy"
+    "deploy": "npx mgr deploy",
+    "test": "npx mgr test"
   },
   "engines": {
     "node": "22",
@@ -105,7 +107,7 @@
     "prettier": "^3.8.3",
     "sass": "^1.99.0",
     "spellchecker": "^3.7.1",
-    "web-manager": "^4.1.41",
+    "web-manager": "^4.1.42",
     "webpack": "^5.106.2",
     "wonderful-fetch": "^2.0.5",
     "wonderful-version": "^1.3.2",
@@ -115,6 +117,7 @@
     "gulp": "^5.0.1"
   },
   "devDependencies": {
-    "prepare-package": "^2.1.0"
+    "prepare-package": "^2.1.0",
+    "puppeteer": "^24.43.1"
   }
 }