ultimate-jekyll-manager 1.1.9 → 1.2.0

package/README.md

@@ -28,6 +28,7 @@
 * **SEO Optimized**: Ultimate Jekyll is fully SEO optimized.
 * **Blazingly Fast**: Ultimate Jekyll is blazingly fast.
 * **NPM & Gulp**: Ultimate Jekyll is fueled by an intuitive incorporation of npm and gulp.
+* **Built-in test framework**: three layers (`build` / `page` / `boot`) — plain Node, headless Chromium tab, headless Chromium against real `_site/` with SW registration verification.
 
 ## 🚀 Getting started
 1. [Create a repo](https://github.com/itw-creative-works/ultimate-jekyll/generate) from the **Ultimate Jekyll** template.
@@ -37,6 +38,49 @@
 npm start
 ```
 
+## 🧪 Testing
+
+UJM ships a built-in three-layer test harness. Write tests under `test/<layer>/*.test.js` and run with:
+
+```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/
+```
+
+Test files use Jest-compatible matchers:
+
+```js
+// test/build/config.test.js
+const Manager = require('ultimate-jekyll-manager/build');
+
+module.exports = {
+  layer: 'build',
+  description: 'config has brand.id',
+  run: async (ctx) => {
+    const cfg = Manager.getConfig('project');
+    ctx.expect(cfg.brand.id).toBeTruthy();
+  },
+};
+```
+
+Boot tests run against your actually-built `_site/` after `npm run build`:
+
+```js
+// test/boot/site.test.js
+module.exports = {
+  layer: 'boot',
+  description: 'home renders + SW registers',
+  inspect: async ({ site, page, expect }) => {
+    await page.goto(site.baseUrl + '/');
+    expect((await page.title()).length).toBeGreaterThan(0);
+  },
+};
+```
+
+Full guide: [docs/test-framework.md](docs/test-framework.md). Boot layer deep-dive: [docs/test-boot-layer.md](docs/test-boot-layer.md).
+
 ## 📦 How to sync with the template
 1. Simply run `npm start` in Terminal to get all the latest updates from the **Ultimate Jekyll template** and launch your website in the browser.
 
@@ -761,23 +805,8 @@ Add this to any js file to ONLY run in development mode (it will be excluded in
   /* @dev-only:end */
 ```
 
-> This project is "ultimate-jekyll", an NPM module that helps   │
-│   streamline development of Jekyll websites. A "consuming       │
-│   project" will require this NPM module to take advantage of    │
-│   its features like automatic folder structure setup, themes,   │
-│   and default pages to get a website up and running in          │
-│   seconds, while allowing further customization down the line.  │
-│   Right now i am struggling on the theme portion of this        │
-│   project. I want the user to be able to define the theme in    │
-│   their _config.yml (which currently they do by setting         │
-│   theme.id). I have some themes from the official bootstrap     │
-│   team. usually a theme comes with a frontend, a backend/admin  │
-│   dashboard, and docs. these 3 subparts of the theme have       │
-│   different html structure and css and js requirements. so i    │
-│   need a super easy system that allows me to make a file in     │
-│   the consuming project, say its the index.html for example,    │
-│   and i should easily be able to put which subseciton (or       │
-│   target as i call it) of the theme to use. so for an agency    │
-│   website i will probably use the frontend target, while for a  │
-│   chat app i will probably use the backend target. however, i   │
-│   need to be able to use
+## 🧰 Sister projects
+
+- [Electron Manager (EM)](https://github.com/itw-creative-works/electron-manager) — same patterns, but for Electron desktop apps
+- [Browser Extension Manager (BXM)](https://github.com/itw-creative-works/browser-extension-manager) — same patterns, but for cross-browser MV3 extensions
+- [Backend Manager (BEM)](https://github.com/itw-creative-works/backend-manager) — Firebase Functions backend framework

package/dist/build.js

@@ -351,5 +351,8 @@ Manager.prototype.processBatches = Manager.processBatches;
 //   };
 // };
 
+// Mix in cross-context mode helpers (isDevelopment/isProduction/isTesting/getVersion).
+require('./utils/mode-helpers.js').attachTo(Manager);
+
 // Export
 module.exports = Manager;

package/dist/cli.js

@@ -17,6 +17,7 @@ const ALIASES = {
   // Tasks
   audit: ['-a', '--audit'],
   translation: ['-t', '--translation'],
+  test: ['--test'],
 };
 
 // Function to resolve command name from aliases

package/dist/commands/test.js

@@ -0,0 +1,56 @@
+// Libraries
+const path    = require('path');
+const fs      = require('fs');
+const Manager = require('../build.js');
+const mgr     = new Manager();
+const logger  = mgr.logger('test');
+const { run } = require('../test/runner.js');
+
+module.exports = async function (options) {
+  const layer       = options.layer    || 'all';
+  const filter      = options.filter   || null;
+  const reporter    = options.reporter || 'pretty';
+  const integration = options.integration === true || options.integration === 'true';
+
+  if (integration) {
+    process.env.UJ_TEST_INTEGRATION = '1';
+  }
+
+  // Canonical signal — every Manager picks this up via isTesting().
+  process.env.UJ_TEST_MODE = 'true';
+
+  // When UJM itself runs its own boot-layer tests (the cwd's package.json is
+  // UJM's package.json), there's no real consumer site to target. Point the
+  // boot runner at the fixture under dist/test/fixtures/consumer-site unless
+  // the caller has already set UJ_TEST_BOOT_PROJECT explicitly.
+  if (!process.env.UJ_TEST_BOOT_PROJECT) {
+    try {
+      const cwdPkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+      if (cwdPkg.name === 'ultimate-jekyll-manager') {
+        process.env.UJ_TEST_BOOT_PROJECT = path.join(__dirname, '..', 'test', 'fixtures', 'consumer-site');
+      }
+    } catch (_) { /* no package.json — leave unset */ }
+  }
+
+  if (reporter !== 'json') {
+    logger.log(`Running tests (layer=${layer}${filter ? ` filter="${filter}"` : ''}${integration ? ' +integration' : ''})`);
+  }
+
+  const result = await run({ layer, filter, reporter });
+
+  if (reporter === 'json') {
+    // Final machine-readable summary.
+    process.stdout.write(JSON.stringify({
+      event:   'summary',
+      passed:  result.passed,
+      failed:  result.failed,
+      skipped: result.skipped,
+      total:   result.passed + result.failed + result.skipped,
+    }) + '\n');
+  }
+
+  if (result.failed > 0) {
+    process.exitCode = 1;
+    throw new Error(`${result.failed} test(s) failed`);
+  }
+};

package/dist/defaults/CLAUDE.md

@@ -1,8 +1,74 @@
-# Identity
-This is a jekyll site that is "consuming" a jekyll template project called Ultimate Jekyll--a collection of components that can be used to build a Jekyll site quickly and efficiently.
+# ========== Default Values ==========
+# Ultimate Jekyll Manager (UJM) — consumer project
 
-## UJ Documentation
-You should have a full understanding of Ultimate Jekyll before editing this project, which can be found at: node_modules/ultimate-jekyll-manager/CLAUDE.md
+> **Auto-managed file.** Everything between `# ========== Default Values ==========` and `# ========== Custom Values ==========` is owned by `ultimate-jekyll-manager` and rewritten on every `npx mgr setup`. Put your own project-specific notes BELOW the `Custom Values` marker — that section is preserved verbatim across setups.
 
-## Project-specific Notes
-Add any notes specific to this project here.
+## Framework
+
+This project consumes **Ultimate Jekyll Manager** (UJM) — a comprehensive framework for building modern Jekyll-powered static sites. UJM provides one-line bootstrap per context (build / frontend / service-worker), a multi-stage gulp pipeline (defaults / distribute / webpack / sass / imagemin / jekyll / audit / translation / minifyHtml / serve), default Jekyll layouts + themes, a frontend ES-module Manager with dynamic per-page module loading, a service worker with Firebase Messaging + cache management, and a built-in three-layer test framework.
+
+**Framework's own docs** (read these for deep-dives; both paths point to the same files, the absolute path works regardless of working directory):
+- Top-level overview: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/CLAUDE.md` (or `node_modules/ultimate-jekyll-manager/CLAUDE.md`)
+- Subsystem references: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/docs/` (or `node_modules/ultimate-jekyll-manager/docs/`)
+
+## Quick start
+
+```bash
+npm start           # dev: clean → setup → bundle exec gulp serve (Jekyll + BrowserSync + livereload)
+npm run build       # production build (UJ_BUILD_MODE=true): clean → setup → full gulp pipeline → _site/
+npm run deploy      # build → `npu sync --message='Deploy'` (publishes _site/)
+npx mgr test        # run framework + project test suites (build / page / boot layers)
+npx mgr audit       # HTML validation + spellcheck + optional Lighthouse
+```
+
+## Where things live
+
+- `src/_config.yml` — Jekyll config: brand, theme, meta, web_manager (Firebase). `Manager.getConfig('project')` reads this. **`brand.id` + `theme.id` are required.**
+- `config/ultimate-jekyll-manager.json` — UJM-specific config (JSON5): purgecss safelist, webpack target, imagemin options, distribute glob patterns. `Manager.getUJMConfig()` reads this.
+- `src/pages/<name>.html` — your custom pages. May contain frontmatter only (and use a UJM `blueprint/*` layout) to customize a default page without writing HTML.
+- `src/_layouts/`, `src/_includes/` — custom layouts / includes that override UJM's defaults.
+- `src/assets/css/main.scss` — shared SCSS. Theme load paths resolve via `__theme__` webpack alias.
+- `src/assets/css/pages/<page>/index.scss` — page-specific styles (compile to `dist/assets/css/pages/<page>/...bundle.css`).
+- `src/assets/js/main.js` — main JS entry.
+- `src/assets/js/pages/<page>/index.js` — page-specific JS. UJM's frontend Manager loads these dynamically based on `data-page-path`.
+- `src/_includes/frontend/sections/{nav,footer}.json` — JSON-driven nav/footer config. UJM renders these into HTML at build time.
+- `hooks/build/{pre,post}.js`, `hooks/middleware/request.js` — optional lifecycle hooks.
+- `_site/` — Jekyll output (the deployable site). Not committed.
+- `dist/` — intermediate compile output (webpack bundles, sass, processed images) before Jekyll merges them into `_site/`.
+- `test/**/*.js` — your project test suites (framework auto-runs them alongside its own).
+
+## Per-context imports
+
+```js
+// Frontend (browser ES module) — every consumer page gets one
+import Manager from 'ultimate-jekyll-manager';
+new Manager().initialize();
+
+// Service worker — at the top of src/service-worker.js
+importScripts('/build.js');   // exposes UJ_BUILD_JSON
+// ...then construct your service-worker Manager
+
+// Build-time / gulp / commands
+const Manager = require('ultimate-jekyll-manager/build');
+```
+
+## Available APIs at runtime
+
+After `new Manager().initialize()`, the frontend Manager exposes:
+- `manager.webManager` — Web Manager singleton (Firebase, auth, analytics, reactive `data-wm-bind` directives)
+- `manager.isDevelopment()` / `isProduction()` / `isTesting()` / `getVersion()` — cross-context helpers
+
+At build time, `require('ultimate-jekyll-manager/build')` exposes:
+- `Manager.getConfig(type)` — read `_config.yml` (`'project'` or `'main'`)
+- `Manager.getPackage(type)` — read `package.json` (`'project'` or `'main'`)
+- `Manager.getUJMConfig()` — read `config/ultimate-jekyll-manager.json`
+- `Manager.getEnvironment()` — `'development'` or `'production'`
+- `Manager.isBuildMode()` / `isQuickMode()` / `isServer()` / `actLikeProduction()` — env-gated flags
+- `Manager.logger(name)` — timestamped logger instance
+- `Manager.require(path)` — escape hatch for UJM transitive deps (use sparingly)
+
+# ========== Custom Values ==========
+
+## Project-specific notes
+
+Add anything specific to THIS project here. Edits below this line are preserved across `npx mgr setup` runs.

package/dist/gulp/tasks/defaults.js

@@ -2,7 +2,7 @@
 const Manager = new (require('../../build.js'));
 const logger = Manager.logger('defaults');
 const { src, dest, watch, series } = require('gulp');
-const through2 = require('through2');
+const { Transform } = require('node:stream');
 const jetpack = require('fs-jetpack');
 const path = require('path');
 const { minimatch } = require('minimatch');
@@ -98,6 +98,15 @@ const FILE_MAP = {
     mergeLines: true, // Merge line-by-line instead of overwriting
   },
 
+  // Consumer CLAUDE.md uses the same marker-based merge as .env/.gitignore.
+  // Framework owns the Default section; consumer owns everything below the Custom marker.
+  // Must come AFTER `**/*.md` (which sets overwrite: false) — `getFileOptions` does
+  // last-match-wins, so this rule's `mergeLines: true` activates the merge path even though
+  // the catch-all would otherwise skip.
+  'CLAUDE.md': {
+    mergeLines: true,
+  },
+
   // Config file with smart merging
   'config/ultimate-jekyll-manager.json': {
     overwrite: true,
@@ -319,8 +328,12 @@ function mergeLineBasedFiles(existingContent, newContent, fileName) {
   result.push(DEFAULT_SECTION_MARKER);
   result.push(...mergedDefaultSection);
 
-  // Add custom section
-  result.push('');
+  // Add custom section. Insert a single blank line before the marker, but only if the
+  // merged default doesn't already end with one — otherwise we'd accumulate an extra blank
+  // line on every merge, breaking idempotency after the first re-run.
+  if (mergedDefaultSection.length === 0 || mergedDefaultSection[mergedDefaultSection.length - 1].trim() !== '') {
+    result.push('');
+  }
   result.push(CUSTOM_SECTION_MARKER);
 
   // First add any user lines that were in default section (moved to custom)
@@ -406,7 +419,9 @@ function defaults(complete, changedFile) {
 }
 
 function customTransform() {
-  return through2.obj(function (file, _, callback) {
+  return new Transform({
+    objectMode: true,
+    transform(file, _, callback) {
     // Skip if it's a directory
     if (file.isDirectory()) {
       return callback(null, file);
@@ -539,6 +554,7 @@ function customTransform() {
 
     // Complete
     return callback();
+    },
   });
 }
 function defaultsWatcher(complete) {

package/dist/gulp/tasks/distribute.js

@@ -2,7 +2,7 @@
 const Manager = new (require('../../build.js'));
 const logger = Manager.logger('distribute');
 const { src, dest, watch, series } = require('gulp');
-const through2 = require('through2');
+const { Transform } = require('node:stream');
 const path = require('path');
 const jetpack = require('fs-jetpack');
 const { template } = require('node-powertools');
@@ -180,38 +180,41 @@ function getFilesRecursive(dir) {
 }
 
 function customTransform() {
-  return through2.obj(function (file, _, callback) {
-    // Skip if it's a directory
-    if (file.isDirectory()) {
-      return callback(null, file);
-    }
+  return new Transform({
+    objectMode: true,
+    transform(file, _, callback) {
+      // Skip if it's a directory
+      if (file.isDirectory()) {
+        return callback(null, file);
+      }
 
-    // Get relative path from src base
-    const relativePath = path.relative(file.base, file.path).replace(/\\/g, '/');
+      // Get relative path from src base
+      const relativePath = path.relative(file.base, file.path).replace(/\\/g, '/');
 
-    // Log
-    if (LOUD) {
-      logger.log(`Processing file: ${relativePath}`);
-    }
+      // Log
+      if (LOUD) {
+        logger.log(`Processing file: ${relativePath}`);
+      }
 
-    // Change path if it starts with 'pages/'
-    // if (relativePath.startsWith('pages/')) {
-    //   // Remove 'pages/' prefix
-    //   const newRelativePath = relativePath.replace(/^pages\//, '');
+      // Change path if it starts with 'pages/'
+      // if (relativePath.startsWith('pages/')) {
+      //   // Remove 'pages/' prefix
+      //   const newRelativePath = relativePath.replace(/^pages\//, '');
 
-    //   // Update file path to remove pages directory
-    //   // This will make src/pages/index.html -> dist/index.html
-    //   file.path = path.join(file.base, newRelativePath);
+      //   // Update file path to remove pages directory
+      //   // This will make src/pages/index.html -> dist/index.html
+      //   file.path = path.join(file.base, newRelativePath);
 
-    //   // Log
-    //   logger.log(`  -> Moving from pages/ to root: ${newRelativePath}`);
-    // }
+      //   // Log
+      //   logger.log(`  -> Moving from pages/ to root: ${newRelativePath}`);
+      // }
 
-    // Push the file
-    this.push(file);
+      // Push the file
+      this.push(file);
 
-    // Continue
-    callback();
+      // Continue
+      callback();
+    },
   });
 }
 

package/dist/gulp/tasks/jsonToHtml.js

@@ -2,7 +2,7 @@
 const Manager = new (require('../../build.js'));
 const logger = Manager.logger('json-to-html');
 const { src, dest, watch, series } = require('gulp');
-const through2 = require('through2');
+const { Transform } = require('node:stream');
 const path = require('path');
 const jetpack = require('fs-jetpack');
 const { template } = require('node-powertools');
@@ -42,90 +42,96 @@ function jsonToHtml(complete) {
 
   // First, copy JSON files to _data directory
   const jsonCopy = src(input)
-    .pipe(through2.obj(function (file, _, callback) {
-      if (file.isDirectory()) {
-        return callback(null, file);
-      }
-
-      try {
-        // Parse JSON5 content
-        const json5Content = file.contents.toString();
-        const parsedData = JSON5.parse(json5Content);
-
-        // Convert to regular JSON (pretty printed for readability)
-        const regularJson = JSON.stringify(parsedData, null, 2);
-
-        // Also write to _data directory for Jekyll to pick up
-        const relativePath = path.relative(file.base, file.path);
-        const dataPath = path.join(dataOutput, relativePath);
-        const dataDir = path.dirname(dataPath);
-
-        // Ensure directory exists
-        jetpack.dir(dataDir);
-
-        // Write regular JSON file to _data
-        jetpack.write(dataPath, regularJson);
-
-        // Track compiled files
-        compiled[dataPath] = true;
-
-        // Update file contents with regular JSON
-        file.contents = Buffer.from(regularJson);
-
-        callback(null, file);
-      } catch (err) {
-        logger.error(`Error parsing JSON5 file ${file.path}: ${err.message}`);
-        callback(err);
-      }
+    .pipe(new Transform({
+      objectMode: true,
+      transform(file, _, callback) {
+        if (file.isDirectory()) {
+          return callback(null, file);
+        }
+
+        try {
+          // Parse JSON5 content
+          const json5Content = file.contents.toString();
+          const parsedData = JSON5.parse(json5Content);
+
+          // Convert to regular JSON (pretty printed for readability)
+          const regularJson = JSON.stringify(parsedData, null, 2);
+
+          // Also write to _data directory for Jekyll to pick up
+          const relativePath = path.relative(file.base, file.path);
+          const dataPath = path.join(dataOutput, relativePath);
+          const dataDir = path.dirname(dataPath);
+
+          // Ensure directory exists
+          jetpack.dir(dataDir);
+
+          // Write regular JSON file to _data
+          jetpack.write(dataPath, regularJson);
+
+          // Track compiled files
+          compiled[dataPath] = true;
+
+          // Update file contents with regular JSON
+          file.contents = Buffer.from(regularJson);
+
+          callback(null, file);
+        } catch (err) {
+          logger.error(`Error parsing JSON5 file ${file.path}: ${err.message}`);
+          callback(err);
+        }
+      },
     }))
     .pipe(dest(dataOutput));
 
   // Then create HTML wrapper files
   const htmlGeneration = src(input)
-    .pipe(through2.obj(function (file, _, callback) {
-      // Skip if it's a directory
-      if (file.isDirectory()) {
-        return callback(null, file);
-      }
-
-      // Get relative path from src/_includes
-      const relativePath = path.relative(file.base, file.path);
-      const relativeDir = path.dirname(relativePath);
-      const basename = path.basename(file.path, '.json');
-
-      // Convert path for Jekyll data reference
-      // _includes/frontend/sections/nav.json -> _includes.frontend.sections.nav
-      const dataPath = '_includes.' + relativePath
-        .replace(/\\/g, '/')
-        .replace('.json', '')
-        .split('/')
-        .join('.');
-
-      // Determine the template path
-      // Look for corresponding template in themes/{theme}/{target}/...
-      const templatePath = `themes/${config.theme.id}/${relativeDir}/${basename}.html`;
-
-      // Create the HTML content
-      const htmlContent = template(INCLUDE_TEMPLATE, {
-        dataPath: dataPath,
-        templatePath: templatePath
-      });
-
-      // Update file contents and extension
-      file.contents = Buffer.from(htmlContent);
-      file.path = file.path.replace('.json', '.html');
-
-      // Log transformation
-      logger.log(`Converting: ${relativePath} -> ${path.basename(file.path)}`);
-      logger.log(`  Data path: site.data.${dataPath}`);
-      logger.log(`  Template: ${templatePath}`);
-
-      // Track the full output path
-      const fullPath = path.resolve(output, path.relative(file.base, file.path));
-      compiled[fullPath] = true;
-
-      // Continue
-      callback(null, file);
+    .pipe(new Transform({
+      objectMode: true,
+      transform(file, _, callback) {
+        // Skip if it's a directory
+        if (file.isDirectory()) {
+          return callback(null, file);
+        }
+
+        // Get relative path from src/_includes
+        const relativePath = path.relative(file.base, file.path);
+        const relativeDir = path.dirname(relativePath);
+        const basename = path.basename(file.path, '.json');
+
+        // Convert path for Jekyll data reference
+        // _includes/frontend/sections/nav.json -> _includes.frontend.sections.nav
+        const dataPath = '_includes.' + relativePath
+          .replace(/\\/g, '/')
+          .replace('.json', '')
+          .split('/')
+          .join('.');
+
+        // Determine the template path
+        // Look for corresponding template in themes/{theme}/{target}/...
+        const templatePath = `themes/${config.theme.id}/${relativeDir}/${basename}.html`;
+
+        // Create the HTML content
+        const htmlContent = template(INCLUDE_TEMPLATE, {
+          dataPath: dataPath,
+          templatePath: templatePath
+        });
+
+        // Update file contents and extension
+        file.contents = Buffer.from(htmlContent);
+        file.path = file.path.replace('.json', '.html');
+
+        // Log transformation
+        logger.log(`Converting: ${relativePath} -> ${path.basename(file.path)}`);
+        logger.log(`  Data path: site.data.${dataPath}`);
+        logger.log(`  Template: ${templatePath}`);
+
+        // Track the full output path
+        const fullPath = path.resolve(output, path.relative(file.base, file.path));
+        compiled[fullPath] = true;
+
+        // Continue
+        callback(null, file);
+      },
     }))
     .pipe(dest(output));