jekyll-theme-zer0 1.27.0 → 1.29.0

data/assets/js/setup-wizard.js

@@ -8,12 +8,45 @@
  * and offers Download / Copy actions.  Pure vanilla JS, no deps
  * beyond Bootstrap 5 (already on the page).
  *
+ * The step container's stable height is NOT handled here. `.wizard-panes` is a
+ * CSS grid with every pane in one cell, so the browser sizes it to the tallest
+ * pane on every reflow. An earlier measurePanes() did this in JS — un-hiding
+ * each pane, reading offsetHeight, restoring it — and came back ~16px short,
+ * which put the shortest step's Back/Next 16px above everyone else's.
+ *
+ * T-040 / #408 added, in the order the pieces depend on each other:
+ *   1. updatePreview()  — now fires on every input anywhere in the wizard,
+ *                         not just on entering step 5, because the preview is
+ *                         a persistent panel rather than a step-5 element.
+ *   2. validateField()  — email/URL checked on blur, `is-invalid` + a message;
+ *                         cleared as soon as the user types again.
+ *   3. saveDraft()      — every value mirrored to localStorage under
+ *                         `zer0-setup-draft`, debounced 300ms, restored on
+ *                         load, acknowledged by the "Draft saved" chip, and
+ *                         cleared when the file is downloaded.
+ *   4. refreshStepper() — the vertical stepper's done/active/locked state. A
+ *                         step is locked until every EARLIER step validates;
+ *                         going back is always allowed.
+ *
+ * Everything degrades: localStorage failures (private mode, quota) are
+ * swallowed, and a missing element short-circuits rather than throwing.
+ *
  * ===================================================================
  */
 
 (function () {
   'use strict';
 
+  var DRAFT_KEY = 'zer0-setup-draft';
+  var DRAFT_DEBOUNCE_MS = 300;
+
+  // Step order is the source of truth for "earlier" / "later" in the stepper.
+  var STEP_IDS = ['tab-identity', 'tab-urls', 'tab-collections', 'tab-analytics', 'tab-review'];
+
+  var draftTimer = null;
+  var chipTimer = null;
+  var restoring = false; // suppresses draft writes while we replay a draft
+
   // ── helpers ────────────────────────────────────────────────────────
 
   /**
@@ -220,6 +253,224 @@
     return lines.join('\n');
   }
 
+  // ── inline validation ──────────────────────────────────────────────
+
+  var VALIDATION_MESSAGES = {
+    email: 'Enter a valid email address, e.g. you@example.com.',
+    url: 'Enter a full URL including https://, e.g. https://example.com.'
+  };
+
+  /**
+   * Validate one field. Empty is always OK — nothing in this wizard is
+   * required, and flagging an untouched field as an error would be wrong.
+   * Returns true when the field is acceptable.
+   */
+  function validateField(el) {
+    if (!el || !el.classList.contains('cfg-field')) return true;
+    var type = (el.getAttribute('type') || '').toLowerCase();
+    if (type !== 'email' && type !== 'url') return true;
+
+    var ok = el.value.trim() === '' || el.checkValidity();
+    el.classList.toggle('is-invalid', !ok);
+
+    var feedback = document.getElementById(el.id + '-feedback');
+    if (feedback) feedback.textContent = ok ? '' : VALIDATION_MESSAGES[type];
+    return ok;
+  }
+
+  /** Is every field inside this pane currently acceptable? */
+  function paneIsValid(pane) {
+    if (!pane) return true;
+    var fields = pane.querySelectorAll('.cfg-field');
+    for (var i = 0; i < fields.length; i += 1) {
+      var el = fields[i];
+      var type = (el.getAttribute('type') || '').toLowerCase();
+      if (type !== 'email' && type !== 'url') continue;
+      if (el.value.trim() !== '' && !el.checkValidity()) return false;
+    }
+    return true;
+  }
+
+  /** The recommended-but-empty fields, by their human label. */
+  function unfilledRecommended() {
+    var missing = [];
+    document.querySelectorAll('[data-recommended]').forEach(function (el) {
+      if (el.value.trim() === '') missing.push(el.getAttribute('data-recommended'));
+    });
+    return missing;
+  }
+
+  /** Render the Review step's warning list. */
+  function renderReviewWarnings() {
+    var host = document.getElementById('wizard-review-warnings');
+    if (!host) return;
+    var missing = unfilledRecommended();
+
+    if (!missing.length) {
+      host.innerHTML = '<div class="alert alert-success mb-0" role="alert">' +
+        '<i class="bi bi-check2-circle"></i> Every recommended field is filled in.</div>';
+      return;
+    }
+
+    var items = missing.map(function (name) {
+      // Labels come from our own markup, but build the DOM through
+      // textContent-equivalent escaping anyway rather than interpolating.
+      var li = document.createElement('li');
+      li.textContent = name;
+      return li.outerHTML;
+    }).join('');
+
+    host.innerHTML = '<div class="alert alert-warning mb-0" role="alert">' +
+      '<i class="bi bi-exclamation-triangle"></i> ' +
+      '<strong>Recommended fields still empty.</strong> The file is valid without them, ' +
+      'but filling them in improves SEO and the site chrome:' +
+      '<ul class="mb-0 mt-2">' + items + '</ul></div>';
+  }
+
+  // ── stepper state ──────────────────────────────────────────────────
+
+  /**
+   * Recompute done / active / locked across the vertical stepper.
+   *
+   * Rule: a step is reachable when every EARLIER step validates. That makes
+   * "Back is always allowed" fall out for free (earlier steps are, by
+   * definition, behind a prefix that already validated) while stopping the
+   * user from carrying a malformed email or URL forward.
+   */
+  function refreshStepper() {
+    var buttons = STEP_IDS.map(function (id) { return document.getElementById(id); });
+    var activeIndex = buttons.findIndex(function (b) {
+      return b && b.classList.contains('is-active');
+    });
+    if (activeIndex < 0) activeIndex = 0;
+
+    var blocked = false;
+    buttons.forEach(function (btn, i) {
+      if (!btn) return;
+      var pane = document.querySelector(btn.getAttribute('data-bs-target'));
+      var valid = paneIsValid(pane);
+
+      var locked = blocked && i > activeIndex;
+      btn.classList.toggle('is-active', i === activeIndex);
+      btn.classList.toggle('is-done', i < activeIndex && valid);
+      btn.classList.toggle('is-locked', locked);
+      btn.disabled = locked;
+      btn.setAttribute('aria-selected', i === activeIndex ? 'true' : 'false');
+
+      var state = btn.querySelector('.wizard-step-state');
+      if (state) {
+        state.textContent = i === activeIndex ? 'current step'
+          : locked ? 'locked until earlier steps are valid'
+            : i < activeIndex && valid ? 'completed' : '';
+      }
+
+      if (!valid) blocked = true;
+    });
+
+    // A Next button cannot skip past a step that has not validated.
+    document.querySelectorAll('.btn-next').forEach(function (btn) {
+      var target = document.getElementById(btn.getAttribute('data-next'));
+      btn.disabled = !!(target && target.disabled);
+    });
+  }
+
+  // ── draft persistence ──────────────────────────────────────────────
+
+  function collectDraft() {
+    var data = { fields: {}, checks: {}, step: null };
+    document.querySelectorAll('#setup-wizard .cfg-field').forEach(function (el) {
+      if (el.id) data.fields[el.id] = el.value;
+    });
+    document.querySelectorAll('#setup-wizard input[type="checkbox"]').forEach(function (el) {
+      if (el.id) data.checks[el.id] = el.checked;
+    });
+    var active = document.querySelector('#wizardTabs .wizard-step.is-active');
+    if (active) data.step = active.id;
+    return data;
+  }
+
+  function showDraftChip() {
+    var chip = document.getElementById('wizard-draft-chip');
+    if (!chip) return;
+    chip.hidden = false;
+    chip.classList.add('is-visible');
+    clearTimeout(chipTimer);
+    chipTimer = setTimeout(function () { chip.classList.remove('is-visible'); }, 2000);
+  }
+
+  function writeDraft() {
+    try {
+      localStorage.setItem(DRAFT_KEY, JSON.stringify(collectDraft()));
+      return true;
+    } catch (e) { /* private mode or quota — the wizard still works */ }
+    return false;
+  }
+
+  function saveDraft() {
+    if (restoring) return;
+    clearTimeout(draftTimer);
+    draftTimer = setTimeout(function () {
+      draftTimer = null;
+      if (writeDraft()) showDraftChip();
+    }, DRAFT_DEBOUNCE_MS);
+  }
+
+  /**
+   * Write a PENDING debounced draft out immediately.
+   *
+   * The 300ms debounce means the last edit before the page goes away is still
+   * only a queued timer, and a timer does not survive navigation: check a
+   * collection box and hit reload inside that window and the change is simply
+   * lost, even though the chip may already have acknowledged an EARLIER save.
+   * `pagehide` and the hidden `visibilitychange` are the two events that still
+   * fire reliably on reload, tab close and bfcache eviction, so the flush hangs
+   * off both. No-op when nothing is queued, so it can never resurrect a draft
+   * that `clearDraft()` has just removed.
+   */
+  function flushDraft() {
+    if (draftTimer === null || restoring) return;
+    clearTimeout(draftTimer);
+    draftTimer = null;
+    writeDraft();
+  }
+
+  function clearDraft() {
+    clearTimeout(draftTimer);
+    draftTimer = null; // …so a later flush cannot write the draft back
+    try { localStorage.removeItem(DRAFT_KEY); } catch (e) { /* ignore */ }
+    var chip = document.getElementById('wizard-draft-chip');
+    if (chip) { chip.classList.remove('is-visible'); chip.hidden = true; }
+  }
+
+  function restoreDraft() {
+    var raw;
+    try { raw = localStorage.getItem(DRAFT_KEY); } catch (e) { return; }
+    if (!raw) return;
+
+    var data;
+    try { data = JSON.parse(raw); } catch (e) { clearDraft(); return; }
+    if (!data || typeof data !== 'object') return;
+
+    restoring = true;
+    Object.keys(data.fields || {}).forEach(function (id) {
+      var el = document.getElementById(id);
+      if (el && el.classList.contains('cfg-field')) el.value = data.fields[id];
+    });
+    Object.keys(data.checks || {}).forEach(function (id) {
+      var el = document.getElementById(id);
+      if (el && el.type === 'checkbox') el.checked = !!data.checks[id];
+    });
+
+    // Re-enter the step the user left off on, but only if the draft still
+    // validates up to there — otherwise a saved bad value could strand them
+    // on a step the stepper would refuse to unlock.
+    var target = data.step && STEP_IDS.indexOf(data.step) !== -1
+      ? document.getElementById(data.step) : null;
+    if (target && !target.disabled) showStep(target);
+
+    restoring = false;
+  }
+
   // ── actions ────────────────────────────────────────────────────────
 
   function updatePreview() {
@@ -229,6 +480,18 @@
     }
   }
 
+  /** Activate a step button, updating stepper state alongside Bootstrap's. */
+  function showStep(btn) {
+    if (!btn || btn.disabled) return;
+    document.querySelectorAll('#wizardTabs .wizard-step').forEach(function (b) {
+      b.classList.remove('is-active');
+    });
+    btn.classList.add('is-active');
+    if (window.bootstrap && window.bootstrap.Tab) new bootstrap.Tab(btn).show();
+    refreshStepper();
+    if (btn.id === 'tab-review') renderReviewWarnings();
+  }
+
   function downloadYAML() {
     var yaml = buildYAML();
     var blob = new Blob([yaml], { type: 'text/yaml;charset=utf-8' });
@@ -240,6 +503,9 @@
     a.click();
     document.body.removeChild(a);
     URL.revokeObjectURL(url);
+    // The draft exists to survive a reload mid-wizard. Once the file is in the
+    // user's hands the wizard is finished, so the draft is stale, not useful.
+    clearDraft();
   }
 
   function copyYAML() {
@@ -257,40 +523,62 @@
   // ── wiring ─────────────────────────────────────────────────────────
 
   document.addEventListener('DOMContentLoaded', function () {
-    // Next / Prev buttons
-    document.querySelectorAll('.btn-next').forEach(function (btn) {
+    var wizard = document.getElementById('setup-wizard');
+    if (!wizard) return;
+
+    // Next / Prev buttons. Back is never blocked; Next is disabled by
+    // refreshStepper() when the step it points at has not unlocked.
+    wizard.querySelectorAll('.btn-next').forEach(function (btn) {
       btn.addEventListener('click', function () {
-        var target = btn.getAttribute('data-next');
-        var tab = document.getElementById(target);
-        if (tab) new bootstrap.Tab(tab).show();
-        updatePreview();
+        showStep(document.getElementById(btn.getAttribute('data-next')));
       });
     });
 
-    document.querySelectorAll('.btn-prev').forEach(function (btn) {
+    wizard.querySelectorAll('.btn-prev').forEach(function (btn) {
       btn.addEventListener('click', function () {
-        var target = btn.getAttribute('data-prev');
-        var tab = document.getElementById(target);
-        if (tab) new bootstrap.Tab(tab).show();
+        showStep(document.getElementById(btn.getAttribute('data-prev')));
       });
     });
 
-    // Live update on review tab activation
-    var reviewTab = document.getElementById('tab-review');
-    if (reviewTab) {
-      reviewTab.addEventListener('shown.bs.tab', updatePreview);
-    }
+    // Clicking a stepper entry directly.
+    wizard.querySelectorAll('#wizardTabs .wizard-step').forEach(function (btn) {
+      btn.addEventListener('click', function () { showStep(btn); });
+    });
+
+    // The preview is persistent now, so it regenerates on EVERY input rather
+    // than on entering step 5. Delegated, so fields added later are covered.
+    wizard.addEventListener('input', function (event) {
+      var el = event.target;
+      updatePreview();
+      // Typing clears a previous error rather than nagging mid-entry; the
+      // re-check happens on blur.
+      if (el.classList && el.classList.contains('is-invalid')) validateField(el);
+      saveDraft();
+    });
+
+    wizard.addEventListener('change', function () {
+      updatePreview();
+      refreshStepper();
+      saveDraft();
+    });
+
+    // Validate email / URL on blur (capture: `blur` does not bubble).
+    wizard.addEventListener('blur', function (event) {
+      if (!event.target.classList || !event.target.classList.contains('cfg-field')) return;
+      validateField(event.target);
+      refreshStepper();
+    }, true);
 
     // Description char count
     var descField = document.getElementById('cfg-description');
     var descCount = document.getElementById('desc-count');
     if (descField && descCount) {
-      descField.addEventListener('input', function () {
-        descCount.textContent = descField.value.length;
-      });
+      var syncCount = function () { descCount.textContent = descField.value.length; };
+      descField.addEventListener('input', syncCount);
+      descCount.textContent = descField.value.length;
     }
 
-    // Download / Copy
+    // Download / Copy — always enabled, at every step.
     var dlBtn = document.getElementById('btn-download');
     if (dlBtn) dlBtn.addEventListener('click', downloadYAML);
 
@@ -300,8 +588,22 @@
     var copyFullBtn = document.getElementById('btn-copy-full');
     if (copyFullBtn) copyFullBtn.addEventListener('click', copyYAML);
 
-    // Initial preview
+    // A queued draft write must not be lost to a reload or a tab close.
+    window.addEventListener('pagehide', flushDraft);
+    document.addEventListener('visibilitychange', function () {
+      if (document.visibilityState === 'hidden') flushDraft();
+    });
+
+    // Order matters: restore values first so the initial preview and stepper
+    // state both reflect the real content.
+    restoreDraft();
+    if (descField && descCount) descCount.textContent = descField.value.length;
     updatePreview();
+    refreshStepper();
+
+    // No pane measurement and no resize listener: the grid in
+    // _setup-wizard.scss keeps `#wizardTabContent` as tall as the tallest pane
+    // at every width, without JS having to be told the width changed.
   });
 
 })();

data/scripts/README.md

@@ -25,6 +25,10 @@ scripts/
 │   ├── pixelate_images.py          # Pure-stdlib pixelate/quantize engine
 │   ├── install-preview-generator   # Preview generator installer
 │   └── validate_preview_urls.py    # Preview URL validator
+├── ci/                    # Helpers called directly by workflow steps
+│   ├── classify_changes.py         # Change classifier (issue-pr-auto-merge)
+│   ├── agent_review_result.py      # Did the Claude content review actually run?
+│   └── test_agent_review_result.py # …its tests (CI-run via test/lib bridge)
 ├── utils/                 # Utility scripts
 │   ├── analyze-commits    # Commit analyzer for version bumps
 │   ├── fix-markdown       # Markdown formatting fixer
@@ -171,6 +175,31 @@ Validate preview image URLs in frontmatter.
 python3 scripts/features/validate_preview_urls.py [--verbose] [--suggestions]
 ```
 
+### CI Helpers (scripts/ci/)
+
+#### `agent_review_result.py`
+
+Decides whether the Claude tier of `ai-content-review.yml` **actually produced a review**, and fails the job when it did not.
+
+Before this existed, the agent step captured the Claude CLI's exit status, echoed it, and then posted whatever landed on stdout as the review. When the OAuth credential was revoked, `Failed to authenticate. API Error: 401 OAuth access token has been revoked.` became the "review" and every job still reported success (issue #418) — for days, across several PRs, with nothing on the checks list to say the editorial review had stopped happening.
+
+Note that a non-zero exit code would not have caught it: the CLI reported the auth failure on stdout. Three conditions are classified — a non-zero exit, no output at all, and a short output that leads with a known CLI failure signature. Any of them writes an explicit failure notice for the sticky comment, emits a `::error::` annotation, and exits 1.
+
+```bash
+python3 scripts/ci/agent_review_result.py \
+  --status "$status" --stdout /tmp/agent-review.md \
+  --stderr /tmp/agent-err.log --out /tmp/agent-review-final.md
+# exit 0 = the review is real · 1 = the tier failed · 2 = bad invocation
+
+python3 scripts/ci/test_agent_review_result.py   # tests, incl. the verbatim #418 output
+```
+
+The tests run in CI through `scripts/test/lib/test_agent_review_result.sh`, which `run_tests.sh` sources and `./scripts/bin/test` executes on every PR.
+
+#### `classify_changes.py`
+
+Classifies a PR's changed files for `issue-pr-auto-merge.yml` (`--content-only`).
+
 ### Content Validation
 
 #### `lint-pages`

data/scripts/bin/audit-consumer

@@ -118,14 +118,35 @@ done
 
 CONSUMER_PATH="$(cd "$CONSUMER_PATH" && pwd)"
 
+# In --format json, stdout must be PURE JSON so `jq` / `json.load` can consume
+# it directly. The human-readable log lines are still useful, so send them to
+# stderr rather than dropping them. (Left on stdout, they made every --format
+# json run unparseable even after the trailing-comma fix.)
+if [[ "$FORMAT" == "json" ]]; then
+    info()    { echo -e "${BLUE}[INFO]${NC} $1" >&2; }
+    step()    { echo -e "${CYAN}[STEP]${NC} $1" >&2; }
+    success() { echo -e "${GREEN}[SUCCESS]${NC} $1" >&2; }
+    warn()    { echo -e "${YELLOW}[WARNING]${NC} $1" >&2; }
+fi
+
 # ---------------------------------------------------------------------------
 step "Auditing consumer: $CONSUMER_PATH"
 
-# Detect or confirm mode
+# CONSUMER_ROOT holds the config/override files; CONSUMER_PATH is where the
+# theme-shadowing files actually live. They differ when the consumer sets
+# Jekyll's `source:` (zer0-pages keeps its whole site tree under `pages/`).
+CONSUMER_ROOT="$CONSUMER_PATH"
+CONSUMER_SOURCE_REL=$(detect_consumer_source "$CONSUMER_ROOT")
+if [[ -n "$CONSUMER_SOURCE_REL" && -d "$CONSUMER_ROOT/$CONSUMER_SOURCE_REL" ]]; then
+    CONSUMER_PATH="$CONSUMER_ROOT/$CONSUMER_SOURCE_REL"
+    info "Jekyll source: $CONSUMER_SOURCE_REL/ — scanning there, not the repo root"
+fi
+
+# Detect or confirm mode (from the repo root, where _config.yml lives)
 if [[ -n "$MODE_OVERRIDE" ]]; then
     MODE="$MODE_OVERRIDE"
 else
-    MODE=$(detect_consumer_mode "$CONSUMER_PATH")
+    MODE=$(detect_consumer_mode "$CONSUMER_ROOT")
     info "Detected mode: $MODE"
 fi
 
@@ -133,7 +154,7 @@ fi
 if [[ -n "$THEME_PATH_OVERRIDE" ]]; then
     RESOLVED_THEME="$THEME_PATH_OVERRIDE"
 else
-    RESOLVED_THEME=$(resolve_theme_path "$MODE" "$CONSUMER_PATH" "$THEME_ROOT")
+    RESOLVED_THEME=$(resolve_theme_path "$MODE" "$CONSUMER_ROOT" "$THEME_ROOT")
 fi
 
 if [[ -z "$RESOLVED_THEME" || ! -d "$RESOLVED_THEME" ]]; then
@@ -149,7 +170,10 @@ if [[ ! -f "$MANIFEST" ]]; then
 fi
 
 # Load overrides manifest from consumer
-OVERRIDES_FILE="$CONSUMER_PATH/.theme-overrides.yml"
+# Declared overrides sit next to _config.yml at the repo root; fall back to the
+# source dir so either placement works.
+OVERRIDES_FILE="$CONSUMER_ROOT/.theme-overrides.yml"
+[[ -f "$OVERRIDES_FILE" ]] || OVERRIDES_FILE="$CONSUMER_PATH/.theme-overrides.yml"
 OVERRIDE_PATHS_TMP=$(mktemp)
 trap 'rm -f "$OVERRIDE_PATHS_TMP"' EXIT
 
@@ -190,8 +214,14 @@ if [[ ${#THEMABLE_DIRS[@]} -eq 0 ]]; then
     THEMABLE_DIRS=("_layouts" "_includes" "_sass" "assets/css" "assets/js")
 fi
 if [[ ${#REQUIRED_PLUGIN_FILES[@]} -eq 0 && ${#OPTIONAL_PLUGIN_FILES[@]} -eq 0 ]]; then
-    REQUIRED_PLUGIN_FILES=("_plugins/obsidian_links.rb")
-    OPTIONAL_PLUGIN_FILES=("_plugins/admin_page_urls.rb" "_plugins/content_statistics_generator.rb" "_plugins/theme_version.rb")
+    # No manifest at all. Nothing is genuinely required (GitHub Pages loads no
+    # local plugins), so every known plugin is offered as optional.
+    OPTIONAL_PLUGIN_FILES=(
+        "_plugins/obsidian_links.rb"
+        "_plugins/admin_page_urls.rb"
+        "_plugins/content_statistics_generator.rb"
+        "_plugins/theme_version.rb"
+    )
 fi
 
 # ---------------------------------------------------------------------------
@@ -316,7 +346,9 @@ fi
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------
-[[ "$FORMAT" == "json" ]] && echo ']}'
+# Entries are printed without a trailing newline (see print_classification),
+# so close the array on its own line.
+[[ "$FORMAT" == "json" ]] && printf '\n]}\n'
 
 if [[ "$FORMAT" == "text" ]]; then
     echo ""