ultimate-jekyll-manager 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -14,6 +14,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+---
+## [1.8.1] - 2026-06-11
+
+### Changed
+
+- **`docs/audit.md` rewritten as the full-audit check catalog (`/omega:ujm audit`).** The two-stage site audit became an ID'd catalog: mirrored universal checks (U-01..U-14 — tests at every layer, XSS, secrets, config canon, doc parity, dead code, dep health, …), UJM-specific checks (UJM-01..UJM-10 — inline-script ban, theme-prefixed classes, content writing rules, SEO meta, purge safelist, reads-vs-writes, page-module pattern, images, a11y), and framework-repo checks (F-01..F-04 — sister parity, defaults sync, docs completeness, green framework suite), with scope auto-detect (consumer vs framework via package.json), a persisted findings report (`.temp/audit/claude-audit.md`), a severity-ordered TodoWrite fix loop, and the `npx mgr audit` automated stage absorbed from the old doc. Wired to the `omega:ujm` router's Audit process; `docs/audit.md` is mirrored across BEM/BXM/EM. CLAUDE.md's docs index updated to match.
+- **package.json `keywords` corrected** — replaced the stale template list (`Autoprefixer`, `imagemin` — not used; `Browsersync` — true but noise) with accurate, discovery-oriented ones (`jekyll`, `static-site`, `static-site-generator`, `website`, `seo`, `gulp`, `sass`, `webpack`, `postcss`). npm-listing metadata only; no behavior change. Mirrored across BEM/BXM/EM.
+
 ---
 ## [1.8.0] - 2026-06-11
 

package/CLAUDE.md

@@ -209,7 +209,7 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 - [docs/test-boot-layer.md](docs/test-boot-layer.md) — boot layer deep-dive (_site/ discovery, HTTP server, fixture vs consumer)
 - [docs/environment-detection.md](docs/environment-detection.md) — `isTesting`/`isDevelopment`/`isProduction`/`getVersion`
 - [docs/jekyll-plugin.md](docs/jekyll-plugin.md) — UJ Powertools gem: filters, tags, page variables (`page.resolved`, `uj_icon`, `uj_hash`, `iftruthy`, etc.)
-- [docs/audit.md](docs/audit.md) — two-stage audit workflow: AI content pass (conventions/XSS/inline scripts) + `npx mgr audit` fix loop
+- [docs/audit.md](docs/audit.md) — full-audit check catalog (U-xx universal / UJM-xx / F-xx IDs with severity + scope), protocol + fix loop, `npx mgr audit` automated stage
 - [docs/migration.md](docs/migration.md) — full migration (old UJ → latest UJM base), `_config.yml` quick-fix schema, revert-posts procedure
 
 ### Project & dev environment

package/docs/audit.md

@@ -1,31 +1,82 @@
 # Audit Workflow
 
-Auditing a UJM site runs in two stages: an AI-powered content pass over the source files, then the automated `npx mgr audit` tool with a systematic fix loop.
+Full-project audit for UJM — runs against a CONSUMER site or the FRAMEWORK repo itself (scope auto-detected). Invoked via the `omega:ujm` skill (`/omega:ujm audit`) or any "audit this site/project" request.
 
-## Stage 1: Content Audit (source files)
+Every check has a stable ID, a severity, and a scope. Findings are reported as `ID @ file:line`, fixed one at a time, then re-verified. The tables below do NOT restate the rules — each check links to the doc that owns the rule and the fix.
 
-1. **Locate all page source files** — `src/pages/**` and `src/_posts/**` (`.html` + `.md`).
-2. **Enforce content conventions** — headings start with action verbs, sentence case, headline/accent structure (see [seo.md](seo.md#content-writing-rules-applies-to-all-pages)). Skip front matter (`meta.title` etc. are controlled by blueprints/layouts), test pages, and blog posts.
-3. **Fix spelling and grammar** in body text — skip code blocks, attributes, URLs.
-4. **XSS / HTML escaping audit** — flag unsafe `innerHTML` assignments; fix with `webManager.utilities().escapeHTML()` (+ `sanitizeURL` for URL sinks). See [xss-prevention.md](xss-prevention.md).
-5. **Inline `<script>` audit (HARD RULE)** — scan all HTML under `src/` for inline script bodies and move them per the playbook in [no-inline-scripts.md](no-inline-scripts.md).
-6. **Summarize** — list files scanned and fixes applied before moving to stage 2.
+## Protocol
 
-## Stage 2: Automated Audit (`npx mgr audit`)
+1. **Detect scope** — read `package.json`: `name` is `ultimate-jekyll-manager` → **framework audit** (U + UJM + F checks); `ultimate-jekyll-manager` in (dev)dependencies → **consumer audit** (U + UJM checks).
+2. **Run the catalog** — every check matching the scope. Search with Grep/Glob/Read over `src/` (+ `test/`, config files); ALWAYS exclude `dist/`, `node_modules/`, `_site/`, `_legacy/`, `_backup/`, `.temp/`, `.cache/`. Record each finding as `ID @ file:line` + a one-line description.
+3. **Persist the report** — write the findings list to `.temp/audit/claude-audit.md` (the same scratch dir `npx mgr audit` uses) so a long fix loop survives session breaks. Summarize counts by severity in chat.
+4. **Fix loop** — TodoWrite per finding, highest severity first, ONE at a time: mark in-progress → root cause → fix → verify → complete. Ask before structural or destructive fixes (file deletions, layout swaps, data changes).
+5. **Re-verify** — re-run every check that produced findings until clean; finish with `npx mgr test` (must be green).
+6. **Doc parity** — if fixes changed behavior, update README / CLAUDE.md / `docs/<topic>.md` / CHANGELOG in the same change set.
 
-1. **Ask the user** whether to run the audit or whether they've already run it; run `npx mgr audit` if needed.
-2. **Locate results** in `.temp/audit/` and read every file COMPLETELY — audit files are large; don't plan from a skim.
-3. **Create a TODO list** — break fixes into atomic tasks, organized by category and priority.
-4. **Fix systematically** — one issue at a time: mark in-progress → navigate → understand root cause → fix → verify → mark complete. Work one category at a time; do NOT attempt to fix everything at once.
-5. **Re-run `npx mgr audit`** after each batch — confirm fixed issues are resolved and no new issues appeared.
+Severity: **CRIT** security or broken functionality · **HIGH** hard-rule violation · **MED** convention drift · **LOW** optional improvement.
+Scope: **C** consumer · **F** framework repo · **B** both.
 
-## Source
+## Universal checks (U-xx)
 
-- Audit task implementation: [`src/gulp/tasks/audit.js`](../src/gulp/tasks/audit.js)
-- Results land in `<projectRoot>/.temp/audit/`
+Mirrored across all four OMEGA frameworks (UJM / BEM / BXM / EM) — same ID means the same check everywhere.
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| U-01 | HIGH | B | Every feature has tests at EVERY layer it surfaces (build / page / boot) — never mocked ([test-framework.md](test-framework.md)) |
+| U-02 | HIGH | B | Test hygiene — real-external-API tests gated behind `TEST_EXTENDED_MODE` in-source (not mocked); no tests that assert nothing ([test-framework.md](test-framework.md)) |
+| U-03 | CRIT | B | XSS — inline `webManager.utilities().escapeHTML(value)` at EVERY DOM sink, `sanitizeURL(url)` at executable URL sinks, zero local escape helpers ([xss-prevention.md](xss-prevention.md)) |
+| U-04 | HIGH | B | web-manager owns Firebase — no direct `firebase` imports anywhere; `webManager.auth()` / `.firestore()` ([javascript-libraries.md](javascript-libraries.md)) |
+| U-05 | HIGH | C | No UJM transitive deps installed in the consumer `package.json` (`firebase`, `web-manager`, …) — webpack `resolve.modules` resolves them ([common-mistakes.md](common-mistakes.md)) |
+| U-06 | HIGH | B | Env behavior gated on the INTENTIONAL check — `isProduction()` or `isDevelopment() \|\| isTesting()`, never `!isDevelopment()`; no ad-hoc `process.env.UJ_*` reads where a helper exists ([environment-detection.md](environment-detection.md)) |
+| U-07 | HIGH | B | Config canon — `src/_config.yml` + `config/ultimate-jekyll-manager.json` match the documented shapes; canonical cross-framework blocks (`brand`, flat 8-key `firebaseConfig`, …) not reinvented ([CLAUDE.md](../CLAUDE.md) §Config flow) |
+| U-08 | CRIT | B | No private credentials committed — `.env`, tokens, secret keys; `.gitignore` covers them. (The Firebase WEB `apiKey` is public by design — do NOT flag it.) |
+| U-09 | HIGH | B | Source discipline — nothing edited in `dist/` / `_site/`; no live code referencing `_legacy/` / `_backup/` ([common-mistakes.md](common-mistakes.md)) |
+| U-10 | MED | B | Doc parity — README / CLAUDE.md / `docs/` / CHANGELOG match shipped behavior; CLAUDE.md < 250 lines; the docs index lists every `docs/*.md`; no stale names for renamed commands/patterns |
+| U-11 | MED | B | SSOT/DRY — no duplicated constants/config/logic; one authoritative home per value, imported everywhere else |
+| U-12 | MED | B | JS conventions — file structure, JSDoc, short-circuit returns, leading logical operators, `fs-jetpack`, one `module.exports` per file (global `js:patterns` skill + [CLAUDE.md](../CLAUDE.md) §File Conventions) |
+| U-13 | MED | B | Dead code & stale patterns — no orphaned `src/` files nothing imports; no leftovers of migrated-away formats ([migration.md](migration.md)); inventory TODO/FIXME (report only) |
+| U-14 | LOW | B | Dependency health — review `npm outdated` / `npm audit`; apply fixes via the `general:update-packages` workflow (includes supply-chain checks) |
+
+## UJM-specific checks
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| UJM-01 | CRIT | B | ZERO inline `<script>` bodies in HTML under `src/` — JS belongs in page modules / `main.js`; migrate per the playbook ([no-inline-scripts.md](no-inline-scripts.md)) |
+| UJM-02 | HIGH | B | Bootstrap-first markup; NO theme-prefixed (`<themeid>-*`) classes in pages/includes — theme SCSS restyles universal classes ([themes.md](themes.md), [css.md](css.md)) |
+| UJM-03 | MED | C | Content writing rules — action-verb headings, sentence case, headline/accent structure; skip front matter, test pages, and blog posts ([seo.md](seo.md#content-writing-rules-applies-to-all-pages)) |
+| UJM-04 | MED | C | Spelling and grammar in body text — skip code blocks, attributes, URLs |
+| UJM-05 | HIGH | C | SEO meta — custom pages carry `meta.title` / `meta.description`; default pages customize via frontmatter per the per-page levels table ([layouts-and-pages.md](layouts-and-pages.md), [seo.md](seo.md)) |
+| UJM-06 | HIGH | B | PurgeCSS — every dynamically-added JS class is safelisted ([purgecss.md](purgecss.md)) |
+| UJM-07 | HIGH | C | Reads-vs-writes — Firestore SDK for dashboard READS only; all WRITES go through Cloud Functions ([javascript-libraries.md](javascript-libraries.md)) |
+| UJM-08 | HIGH | B | Page JS pattern — modules at `src/assets/js/pages/<path>/index.js` with element-existence guards; forms via FormManager; no Liquid in JS (use `data-*` / `<template>` bridges) ([assets.md](assets.md), [page-loading.md](page-loading.md), [no-inline-scripts.md](no-inline-scripts.md)) |
+| UJM-09 | MED | C | Images — imagemin source-size constraints respected, `data-lazy` lazy loading used, `@post/` shortcut in blog posts ([images.md](images.md), [lazy-loading.md](lazy-loading.md)) |
+| UJM-10 | MED | B | Accessibility basics — meaningful `alt` text, labeled form fields, real `<button>`/`<a>` elements (no clickable `div`s) |
+
+## Automated stage: `npx mgr audit`
+
+After (or alongside) the catalog, run UJM's built-in audit tool — HTML validation + spellcheck + optional Lighthouse:
+
+1. **Ask the user** whether to run it or whether they've already run it; run `npx mgr audit` if needed.
+2. **Read EVERY file in `.temp/audit/` COMPLETELY** — audit outputs are large; don't plan from a skim.
+3. **Fold the findings into the same TodoWrite fix loop** — one category at a time; do NOT attempt everything at once.
+4. **Re-run `npx mgr audit` after each batch** — confirm fixed issues resolved and no new ones appeared.
+
+Implementation: [`src/gulp/tasks/audit.js`](../src/gulp/tasks/audit.js); results land in `<projectRoot>/.temp/audit/`.
+
+## Framework-repo checks (F-xx)
+
+Only when auditing the UJM repo itself. Mirrored across the four frameworks.
+
+| ID | Sev | Check |
+|----|-----|-------|
+| F-01 | MED | Sister parity — mirrored sections (config shapes, test contract, CLAUDE.md skeleton, shared env/test conventions) in sync with BEM / BXM / EM; deviations are deliberate and documented |
+| F-02 | HIGH | Consumer-shipped defaults in sync — what `npx mgr setup` scaffolds matches current conventions and docs |
+| F-03 | MED | Docs completeness — every `docs/*.md` indexed in CLAUDE.md; every subsystem has a doc; no "(planned)" links for things that have shipped |
+| F-04 | HIGH | `npx mgr test mgr:` green before treating the audit as complete |
 
 ## See also
 
-- [seo.md](seo.md) — the content conventions stage 1 enforces
-- [xss-prevention.md](xss-prevention.md) — escaping rules
-- [no-inline-scripts.md](no-inline-scripts.md) — the inline-script migration playbook
+- [seo.md](seo.md) — the content conventions UJM-03 enforces
+- [xss-prevention.md](xss-prevention.md) — the escaping rules behind U-03
+- [no-inline-scripts.md](no-inline-scripts.md) — the UJM-01 migration playbook
+- [test-framework.md](test-framework.md) — the layers behind U-01 / U-02

package/logs/test.log

@@ -1,6 +1,6 @@
-# ujm log — 2026-06-11T08:01:19.096Z — pid=72007
-[01:01:19] 'test': Running tests (layer=all)
-[01:01:19] 'test': Test mode: normal (external APIs skipped)
+# ujm log — 2026-06-11T10:04:30.890Z — pid=33077
+[03:04:30] 'test': Running tests (layer=all)
+[03:04:30] 'test': Test mode: normal (external APIs skipped)
 
   Ultimate Jekyll Manager Tests
 
@@ -10,30 +10,30 @@
       ✓ stripAnsi removes color escape codes (0ms)
 hello world
 colored line
-      ✓ attach + stdout.write + detach: file contains the writes (1ms)
+      ✓ attach + stdout.write + detach: file contains the writes (0ms)
       ✓ idempotent: attaching twice with same name returns same fd (0ms)
-      ✓ attach with falsy name returns null and does nothing (0ms)
+      ✓ attach with falsy name returns null and does nothing (1ms)
     ⤷ CLI alias resolution
       ✓ cli.js exports a Main class (0ms)
       ✓ all expected commands exist on disk (0ms)
-      ✓ each command module exports an async function (6ms)
+      ✓ each command module exports an async function (7ms)
     ⤷ collectTextNodes (utils/collectTextNodes.js)
-      ✓ extracts page title (145ms)
+      ✓ extracts page title (177ms)
       ✓ skips <script> and <style> (1ms)
-    ✓ spellcheck dictionary (utils/dictionary.js) (1ms)
+    ✓ spellcheck dictionary (utils/dictionary.js) (0ms)
     ⤷ expect() matcher set
       ✓ toBe + toEqual basics (0ms)
       ✓ .not negates (0ms)
       ✓ toContain works on arrays and strings (0ms)
       ✓ toThrow catches sync + async throws (0ms)
-      ✓ toBeGreaterThan / toBeLessThan (0ms)
+      ✓ toBeGreaterThan / toBeLessThan (1ms)
       ✓ failing assertions throw AssertionError (0ms)
     ✓ package.json exports resolve to real files in dist/ (0ms)
     ⤷ Logger (src/lib/logger.js)
       ✓ Logger constructor stores name (0ms)
       ✓ Logger exposes log/error/warn/info methods (0ms)
       ✓ Logger.format is chalk (0ms)
-      ✓ Logger output goes through console with prefix (0ms)
+      ✓ Logger output goes through console with prefix (1ms)
     ⤷ Manager (build.js) public surface
       ✓ Manager constructor is a function (0ms)
       ✓ static methods match prototype methods (0ms)
@@ -42,13 +42,13 @@ colored line
       ✓ isServer reflects UJ_IS_SERVER env (0ms)
       ✓ getEnvironment maps to development/testing/production (0ms)
       ✓ actLikeProduction is true when isBuildMode OR UJ_AUDIT_FORCE (0ms)
-      ✓ getRootPath("package") points at UJM root (1ms)
+      ✓ getRootPath("package") points at UJM root (0ms)
       ✓ getMemoryUsage returns shape with MB-sized numbers (0ms)
       ✓ getArguments returns object with _ array + boolean defaults (0ms)
       ✓ logger returns object with log/error/warn/info methods (0ms)
       ✓ processBatches processes items in chunks and returns flat results (0ms)
     ⤷ mergeJekyllConfigs (utils/merge-jekyll-configs.js)
-      ✓ merges collections from both configs (project additions win) (6ms)
+      ✓ merges collections from both configs (project additions win) (5ms)
       ✓ dedups defaults by scope key (project wins) (2ms)
       ✓ returns null when there is nothing to merge (1ms)
     ⤷ mode-helpers (isTesting / isDevelopment / isProduction / getVersion)
@@ -59,34 +59,34 @@ colored line
       ✓ invariant: is*() exactly matches getEnvironment() + mutually exclusive (every scenario) (1ms)
       ✓ getVersion returns a non-empty string when run from a package (0ms)
     ⤷ createTemplateTransform (utils/template-transform.js)
-      ✓ replaces [site.theme.id] with config value in .html files (2ms)
-      ✓ leaves non-matching extensions untouched (e.g. .css) (0ms)
+      ✓ replaces [site.theme.id] with config value in .html files (1ms)
+      ✓ leaves non-matching extensions untouched (e.g. .css) (1ms)
       ✓ passes directories through untouched (0ms)
     ⤷ node-powertools templating brackets ({} and [])
       ✓ default { } brackets resolve nested keys (0ms)
-      ✓ [ ] brackets resolve nested keys when explicitly configured (1ms)
+      ✓ [ ] brackets resolve nested keys when explicitly configured (0ms)
       ✓ [ ] brackets leave Jekyll {{ }} placeholders alone (0ms)
     ⤷ theme contract (structure, swappability, cross-theme JS contracts)
       ✓ _template: entry files + config contract (0ms)
       ✓ classy: entry files + config contract (0ms)
       ✓ neobrutalism: entry files + config contract (0ms)
-      ✓ newsflash: entry files + config contract (1ms)
-      ✓ _template: layouts swappable, markup clean (1ms)
-      ✓ classy: layouts swappable, markup clean (12ms)
-      ✓ neobrutalism: layouts swappable, markup clean (2ms)
+      ✓ newsflash: entry files + config contract (0ms)
+      ✓ _template: layouts swappable, markup clean (2ms)
+      ✓ classy: layouts swappable, markup clean (14ms)
+      ✓ neobrutalism: layouts swappable, markup clean (1ms)
       ✓ newsflash: layouts swappable, markup clean (3ms)
       ✓ _template: cross-theme JS contracts (0ms)
-      ✓ classy: cross-theme JS contracts (1ms)
-      ✓ neobrutalism: cross-theme JS contracts (1ms)
-      ✓ newsflash: cross-theme JS contracts (0ms)
-      ✓ page asset files match a declared asset_path shape (7ms)
+      ✓ classy: cross-theme JS contracts (2ms)
+      ✓ neobrutalism: cross-theme JS contracts (0ms)
+      ✓ newsflash: cross-theme JS contracts (1ms)
+      ✓ page asset files match a declared asset_path shape (8ms)
     ⤷ validateYAMLFrontMatter (utils/_validate-yaml.js)
-      ✓ returns { valid: true } for a file with valid frontmatter (3ms)
-      ✓ returns { valid: true } when no frontmatter present (0ms)
+      ✓ returns { valid: true } for a file with valid frontmatter (1ms)
+      ✓ returns { valid: true } when no frontmatter present (1ms)
       ✓ flags malformed YAML frontmatter as invalid with error message (1ms)
     ⤷ page-layer baseline (DOM + fetch + storage)
-      ✓ document is interactive or complete (0ms)
-      ✓ fetch() works against the local harness server (7ms)
+      ✓ document is interactive or complete (3ms)
+      ✓ fetch() works against the local harness server (9ms)
       ✓ localStorage is available (1ms)
     ⤷ harness globals (window.Configuration + dataset)
       ✓ window.Configuration has brand + theme + web_manager (0ms)
@@ -96,16 +96,16 @@ colored line
       ✓ template#prerendered-icons exists and has the test icon (1ms)
       ✓ looking up a missing icon returns null (0ms)
     ⤷ boot tests (consumer _site/)
-      ✓ /service-worker.js served with javascript content type (105ms)
-      ✓ index.html registers SW and reaches activated state (202ms)
-      ✓ SW responds to get-cache-name message with brand-id pattern (116ms)
-      ✓ home page renders with title + body content (210ms)
-      ✓ /about resolves via Jekyll-style .html fallback (93ms)
-      ✓ build.json is served with brand metadata (109ms)
-      ✓ CSS bundle served with text/css content type (94ms)
+      ✓ /service-worker.js served with javascript content type (113ms)
+      ✓ index.html registers SW and reaches activated state (226ms)
+      ✓ SW responds to get-cache-name message with brand-id pattern (104ms)
+      ✓ home page renders with title + body content (218ms)
+      ✓ /about resolves via Jekyll-style .html fallback (103ms)
+      ✓ build.json is served with brand metadata (98ms)
+      ✓ CSS bundle served with text/css content type (88ms)
 
   Results
     80 passing
 
-    Total: 80 tests in 24960ms
+    Total: 80 tests in 4505ms
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate-jekyll-manager",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Ultimate Jekyll dependency manager",
   "main": "dist/index.js",
   "exports": {
@@ -47,14 +47,15 @@
     "url": "https://github.com/itw-creative-works/ultimate-jekyll.git"
   },
   "keywords": [
-    "Autoprefixer",
-    "Browsersync",
+    "jekyll",
+    "static-site",
+    "static-site-generator",
+    "website",
+    "seo",
     "gulp",
-    "imagemin",
-    "Jekyll",
-    "PostCSS",
-    "Sass",
-    "Webpack"
+    "sass",
+    "webpack",
+    "postcss"
   ],
   "author": "ITW Creative Works",
   "license": "MIT",

package/.claude/scheduled_tasks.lock

@@ -1 +0,0 @@
-{"sessionId":"76fefdf0-10f3-4795-b5eb-56e35f724e5e","pid":53082,"procStart":"Wed Jun 10 11:57:56 2026","acquiredAt":1781141001890}