jekyll-theme-zer0 1.28.0 → 1.30.0

data/scripts/bin/manifest

@@ -67,19 +67,40 @@ THEME_DATA_PATHS=(
     "_data/ui-text.yml"
 )
 
-# Plugins that remote_theme consumers MUST vendor locally (GitHub Pages won't
-# load plugins from a remote theme).
-REQUIRED_PLUGIN_PATHS=(
-    "_plugins/obsidian_links.rb"
-)
+# Plugins that remote_theme consumers MUST vendor locally.
+#
+# Deliberately empty. Nothing the theme ships is mandatory for a stock
+# remote_theme consumer: GitHub Pages builds in safe mode, so it does not load
+# ANY local plugin — vendoring one there is inert, not required.
+REQUIRED_PLUGIN_PATHS=()
 
-# Optional plugins that consumers can vendor for enhanced functionality.
+# Optional plugins a consumer can vendor for enhanced functionality. These only
+# execute on a self-built (vanilla Jekyll) site, never on default GitHub Pages.
+#
+# `obsidian_links.rb` sits here, not above, because obsidian.instructions.md is
+# explicit that it is opt-in ("skipped under the github-pages gem"; "an
+# SEO-quality enhancement for forks that self-build") and that the Liquid + JS
+# path is the primary one. Listing it as required made the audit demand a file
+# that cannot run, flagging MISSING_PLUGIN on seven fleet consumers that have
+# no Obsidian content at all.
 OPTIONAL_PLUGIN_PATHS=(
+    "_plugins/obsidian_links.rb"
     "_plugins/admin_page_urls.rb"
     "_plugins/content_statistics_generator.rb"
     "_plugins/theme_version.rb"
 )
 
+# Emit YAML list items, or an empty flow sequence when there are none.
+# `printf '  - %s\n'` with zero args would otherwise emit a bare `  - `, i.e. a
+# phantom empty entry in the list.
+yaml_list_items() {
+    if [[ $# -eq 0 ]]; then
+        echo "  []"
+    else
+        printf '  - %s\n' "$@"
+    fi
+}
+
 # ---------------------------------------------------------------------------
 # Argument parsing
 DRY_RUN=false
@@ -153,17 +174,19 @@ $(printf '  - %s\n' "${THEMABLE_PATHS[@]}")
 theme_data_paths:
 $(printf '  - %s\n' "${THEME_DATA_PATHS[@]}")
 
-# Plugin files that consumers using remote_theme MUST vendor locally.
-# GitHub Pages does not load plugins from a remote_theme source.
+# Plugin files a consumer MUST vendor locally. Empty by design: GitHub Pages
+# builds in safe mode and loads no local plugins at all, so nothing the theme
+# ships is mandatory for a stock remote_theme consumer.
 required_plugin_paths:
-$(printf '  - %s\n' "${REQUIRED_PLUGIN_PATHS[@]}")
-# Optional plugins consumers can vendor for enhanced functionality.
+$(yaml_list_items ${REQUIRED_PLUGIN_PATHS[@]+"${REQUIRED_PLUGIN_PATHS[@]}"})
+# Optional plugins consumers can vendor for enhanced functionality. These run
+# only on self-built (vanilla Jekyll) sites, never on default GitHub Pages.
 optional_plugin_paths:
-$(printf '  - %s\n' "${OPTIONAL_PLUGIN_PATHS[@]}")
+$(yaml_list_items ${OPTIONAL_PLUGIN_PATHS[@]+"${OPTIONAL_PLUGIN_PATHS[@]}"})
 
 # Legacy alias — all plugin paths combined (kept for backward compatibility).
 plugin_paths:
-$(printf '  - %s\n' "${REQUIRED_PLUGIN_PATHS[@]}" "${OPTIONAL_PLUGIN_PATHS[@]}")
+$(yaml_list_items ${REQUIRED_PLUGIN_PATHS[@]+"${REQUIRED_PLUGIN_PATHS[@]}"} ${OPTIONAL_PLUGIN_PATHS[@]+"${OPTIONAL_PLUGIN_PATHS[@]}"})
 
 # Jekyll config keys this theme expects.
 config_schema:

data/scripts/ci/agent_review_result.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Decide whether the Claude content review ACTUALLY ran, and fail loudly if not.
+
+WHY THIS EXISTS (issue #418)
+----------------------------
+`.github/workflows/ai-content-review.yml`'s agent step used to capture the
+Claude CLI's exit status, echo it, and then never act on it. Whatever landed on
+stdout was posted verbatim under the `ai-content-review-agent` sticky marker and
+the step exited 0.
+
+So when the OAuth credential was revoked (2026-08-18 → 08-24) the CLI printed
+
+    Failed to authenticate. API Error: 401 OAuth access token has been revoked.
+
+to STDOUT, that single line became the "review", and every job reported success.
+Run 32618860829 concluded `success` while posting exactly that to PR #414; run
+32656168775 shows all three agent steps green under the same conditions. Nothing
+in the checks list, the run conclusion, or the annotations distinguished a
+working editorial review from a dead one — for days, across several PRs.
+
+Note what that rules out: a non-zero exit code is NOT sufficient to detect this.
+The CLI reported the auth failure on stdout, and the step's own control flow
+swallowed the status regardless. So all three ways the tier can be dead are
+classified here:
+
+  1. the CLI exited non-zero;
+  2. it produced no output at all;
+  3. it produced only a failure notice (the observed 401 case).
+
+On any of those this writes an explicit failure notice for the sticky comment,
+emits a ``::error::`` annotation so the condition is visible in the checks UI,
+and exits 1 so the job goes red. The workflow's `Post agent review` step is
+`if: always()`, so the comment is still posted — the reader gets a notice that
+says the review did not run, instead of a raw API error dressed as a review.
+
+Usage:
+    python3 scripts/ci/agent_review_result.py \\
+        --status <claude-exit-code> \\
+        --stdout <file> [--stderr <file>] \\
+        --out <comment-body-file>
+
+Exit: 0 the review is real · 1 the tier failed · 2 bad invocation
+
+Tests: scripts/ci/test_agent_review_result.py (run in CI via
+scripts/test/lib/test_agent_review_result.sh → ./scripts/bin/test).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+TITLE = "## 🤖 Claude Code Content Review"
+
+# Failure signatures the Claude CLI prints INSTEAD of a review. Kept narrow on
+# purpose: every entry is a string the CLI emits on its own.
+FAILURE_SIGNATURES = re.compile(
+    r"Failed to authenticate"
+    r"|OAuth access token has been revoked"
+    r"|API Error: (?:401|403|429|5\d\d)"
+    r"|authentication_error"
+    r"|invalid_api_key"
+    r"|Invalid API key"
+    r"|Credit balance is too low"
+    r"|Please run [`'\"]?claude login",
+    re.IGNORECASE,
+)
+
+# A genuine review is a structured Markdown document — a verdict, per-file
+# findings, a summary. A failure notice is a line or two, and the failure is the
+# FIRST thing on it. Requiring all three (short body, signature, signature near
+# the top) stops a review that legitimately *discusses* an auth error from being
+# thrown away as a failure — reviewing this repo's own credential-troubleshooting
+# page would otherwise fail its own PR. Both directions are covered by the tests,
+# and the bound is deliberately tight: an ambiguous LONG output containing an
+# error is better shown to a human than silently discarded. A genuinely broken
+# run that is also verbose almost always exits non-zero, which rule 1 catches.
+MAX_FAILURE_NOTICE_LINES = 5
+FAILURE_SIGNATURE_HEAD_LINES = 3
+
+
+def nonblank_lines(text: str) -> list[str]:
+    return [ln for ln in text.splitlines() if ln.strip()]
+
+
+def classify(status: int, stdout: str) -> str | None:
+    """Return a human-readable failure reason, or None if the review is real."""
+    lines = nonblank_lines(stdout)
+    if status != 0:
+        return f"the Claude CLI exited with status `{status}`"
+    if not lines:
+        return "the agent produced no output"
+    head = "\n".join(lines[:FAILURE_SIGNATURE_HEAD_LINES])
+    if len(lines) <= MAX_FAILURE_NOTICE_LINES and FAILURE_SIGNATURES.search(head):
+        return "the agent reported a credential / API failure instead of a review"
+    return None
+
+
+def _details(summary: str, body: str) -> list[str]:
+    tail = "\n".join(body.splitlines()[-20:])
+    return [f"<details><summary>{summary}</summary>", "", "```", tail, "```", "", "</details>", ""]
+
+
+def render_failure(reason: str, status: int, stdout: str, stderr: str) -> str:
+    out = [
+        TITLE,
+        "",
+        "> [!CAUTION]",
+        f"> **The editorial review did not run** — {reason}.",
+        "> This comment is a failure notice, not a review. The job has been",
+        "> failed on purpose so the condition is visible on the checks list",
+        "> rather than only in this comment.",
+        "",
+        f"Claude CLI exit status: `{status}`",
+        "",
+    ]
+    if stdout.strip():
+        out += _details("Agent stdout", stdout)
+    if stderr.strip():
+        out += _details("Agent stderr (tail)", stderr)
+    out += [
+        "If this is a credential problem, rotate `CLAUDE_CODE_OAUTH_TOKEN` for this",
+        "repository — see `docs/TOKEN-ROTATION.md` in bamr87/bamr87. The deterministic",
+        "tier (`scripts/content-review.rb`) is unaffected and posts separately.",
+        "",
+    ]
+    return "\n".join(out)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--status", type=int, required=True, help="claude CLI exit code")
+    p.add_argument("--stdout", required=True, help="file holding the agent's stdout")
+    p.add_argument("--stderr", default=None, help="file holding the agent's stderr")
+    p.add_argument("--out", required=True, help="file to write the sticky comment body to")
+    args = p.parse_args(argv)
+
+    stdout = Path(args.stdout).read_text(encoding="utf-8", errors="replace") \
+        if Path(args.stdout).exists() else ""
+    stderr = ""
+    if args.stderr and Path(args.stderr).exists():
+        stderr = Path(args.stderr).read_text(encoding="utf-8", errors="replace")
+
+    reason = classify(args.status, stdout)
+    out_path = Path(args.out)
+
+    if reason is None:
+        out_path.write_text(f"{TITLE}\n\n{stdout}", encoding="utf-8")
+        print(f"agent-review-result: review looks real "
+              f"({len(nonblank_lines(stdout))} non-blank lines).")
+        return 0
+
+    out_path.write_text(render_failure(reason, args.status, stdout, stderr), encoding="utf-8")
+    print(f"::error title=Claude content review did not run::{reason} "
+          f"(claude exit {args.status}). The sticky comment carries a failure notice, "
+          f"not a review.")
+    print(f"agent-review-result: FAILED — {reason}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/ci/test_agent_review_result.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Unit tests for scripts/ci/agent_review_result.py (issue #418).
+
+The bug these guard against: the Claude tier of ai-content-review.yml posted
+
+    Failed to authenticate. API Error: 401 OAuth access token has been revoked.
+
+into PR #414 as its review, and the job still reported success. The credential
+has since been rotated, but the SWALLOW is the durable defect — it would hide
+the next revoked token exactly as well as it hid this one.
+
+The first fixture below is that output verbatim, copied from the comment the
+workflow actually posted (2026-08-23T04:51:47Z, run 32618860829). If the guard
+ever stops failing on it, the regression is back.
+
+Both directions are covered. A real review must NOT be flagged — including one
+whose prose legitimately quotes an auth error, which is the false positive a
+bare `grep 'Failed to authenticate'` would produce (and which would fire on this
+repo's own troubleshooting docs).
+
+Dependency-light on purpose: standard library only, so it runs anywhere the
+workflow does.
+
+    python3 scripts/ci/test_agent_review_result.py
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import agent_review_result as arr  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+WORKFLOW = REPO_ROOT / ".github" / "workflows" / "ai-content-review.yml"
+
+CHECKS: list[tuple[str, bool]] = []
+
+
+def check(label: str, ok: bool) -> None:
+    CHECKS.append((label, bool(ok)))
+
+
+# The 401 exactly as the CLI printed it and the workflow posted it.
+AUTH_401 = "Failed to authenticate. API Error: 401 OAuth access token has been revoked.\n"
+
+REAL_REVIEW = """**Verdict:** approve with minor suggestions
+
+### pages/_docs/getting-started.md
+
+- The `description` front matter reads as a keyword list rather than a sentence.
+  Rewrite it as prose so search snippets are readable.
+- The second H2 duplicates the page title; demote it to an H3 or cut it.
+- Two code fences are missing a language tag, so they render unhighlighted.
+- Alt text on the architecture diagram describes the file, not the picture.
+
+### pages/_docs/configuration.md
+
+- Consistent terminology: this page says "config file" where the rest of the
+  docs say `_config.yml`. Pick one.
+- The table of collection defaults is missing the `books` collection added in
+  v1.19, so the page is incomplete rather than merely terse.
+- Sentence length in "Advanced overrides" averages 38 words; split the longest.
+
+### Summary
+
+Both files are accurate and well-organised. The findings above are polish, not
+correctness — nothing here blocks the merge.
+"""
+
+# A real review that TALKS about auth failures. Must not be mistaken for one.
+REVIEW_ABOUT_AUTH = """**Verdict:** approve
+
+### docs/troubleshooting/credentials.md
+
+- The page explains what to do when the CLI prints "Failed to authenticate. API
+  Error: 401 OAuth access token has been revoked." — good, that is the exact
+  string users will search for, so keep it verbatim rather than paraphrasing.
+- Add a cross-link to the rotation runbook; the reader is told to "rotate the
+  token" with no pointer to how.
+- The `authentication_error` example block is missing a language tag.
+- Consider noting that the deterministic review tier keeps working while the
+  credential is broken, since that surprised at least one reader.
+- Front matter `lastmod` is stale by two releases.
+
+### Summary
+
+Accurate and genuinely useful. Only polish items above; the troubleshooting
+steps themselves check out against the current workflow definition.
+"""
+
+
+def run_guard(status: int, stdout: str, stderr: str = "") -> tuple[int, str]:
+    """Invoke the guard end-to-end; return (exit code, comment body)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        d = Path(tmp)
+        (d / "out.txt").write_text(stdout, encoding="utf-8")
+        (d / "err.txt").write_text(stderr, encoding="utf-8")
+        rc = arr.main([
+            "--status", str(status),
+            "--stdout", str(d / "out.txt"),
+            "--stderr", str(d / "err.txt"),
+            "--out", str(d / "body.md"),
+        ])
+        return rc, (d / "body.md").read_text(encoding="utf-8")
+
+
+def main() -> int:
+    # --- the observed failure, verbatim ------------------------------------ #
+    rc, body = run_guard(0, AUTH_401)
+    check("the verbatim PR #414 401 fails the step (exit 1) even on claude exit 0", rc == 1)
+    check("the 401 comment body says the review did not run", "did not run" in body)
+    check("the raw 401 line is no longer posted as if it were the review",
+          not body.startswith(f"{arr.TITLE}\n\nFailed to authenticate"))
+    check("the failure notice is visibly a caution, not a review", "[!CAUTION]" in body)
+
+    rc, _ = run_guard(1, AUTH_401)
+    check("a non-zero claude exit fails the step", rc == 1)
+
+    # --- nothing came back -------------------------------------------------- #
+    rc, body = run_guard(0, "")
+    check("empty agent output fails the step", rc == 1)
+    check("the empty-output notice names the reason", "no output" in body)
+
+    rc, _ = run_guard(0, "\n   \n\t\n")
+    check("whitespace-only agent output fails the step", rc == 1)
+
+    # --- other credential failures ------------------------------------------ #
+    rc, _ = run_guard(0, "API Error: 400 Credit balance is too low to access the API.\n")
+    check("a credit-balance failure fails the step", rc == 1)
+    rc, _ = run_guard(0, "Invalid API key · Please run `claude login`\n")
+    check("an invalid-key failure fails the step", rc == 1)
+    rc, _ = run_guard(0, "API Error: 429 rate limit exceeded\n")
+    check("a rate-limit failure fails the step", rc == 1)
+
+    # --- real reviews pass --------------------------------------------------- #
+    rc, body = run_guard(0, REAL_REVIEW)
+    check("a genuine multi-section review passes", rc == 0)
+    check("the real review is posted under the review heading", "**Verdict:**" in body)
+
+    rc, _ = run_guard(0, REVIEW_ABOUT_AUTH)
+    check("a long review that QUOTES an auth error is not mistaken for a failure", rc == 0)
+
+    # --- the workflow actually uses the guard -------------------------------- #
+    # Without this the fix is one deleted line away from returning, and nothing
+    # in the fixture tests above would notice.
+    wf = WORKFLOW.read_text(encoding="utf-8")
+    check("ai-content-review.yml invokes the guard",
+          "scripts/ci/agent_review_result.py" in wf)
+    check("the agent step no longer ends by piping stdout into the comment body",
+          not re.search(r"cat /tmp/agent-review\.md\s*\n\s*\}\s*>\s*/tmp/agent-review-final\.md", wf))
+    check("the AI gate no longer implies a present credential is a working one",
+          "not validity" in wf)
+
+    failed = [label for label, ok in CHECKS if not ok]
+    print()
+    for label, ok in CHECKS:
+        print(f"  {'PASS' if ok else 'FAIL'}  {label}")
+    print()
+    if failed:
+        print(f"FAILED ({len(failed)}/{len(CHECKS)})")
+        return 1
+    print(f"OK ({len(CHECKS)} checks)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())