jekyll-theme-zer0 1.27.0 → 1.29.0

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())

data/scripts/design-system-check.rb

@@ -0,0 +1,170 @@
+#!/usr/bin/env ruby
+# Feature: ZER0-081
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# design-system-check — token parity between the theme and its Claude Design
+# mirror.
+#
+# The `--zer0-*` design tokens live twice on purpose:
+#   - `_sass/tokens/*.scss`         — the source of truth the theme compiles
+#   - `_design-system/tokens/*.css` — the mirror pushed to the Claude Design
+#                                     project (see _design-system/SYNC.md)
+#
+# This check keeps the two in lockstep so the design system can be built from
+# either side without silent drift:
+#
+#   1. Per file pair: the sets of `--zer0-*` names must match, and every value
+#      must resolve to the same string. `var(--x, fallback)` wrappers are
+#      resolved against the mirror's concrete `--bs-*`/`--bd-*` primitives, so
+#      the theme's alias form and the mirror's self-contained form compare
+#      equal.
+#   2. Skins: `_sass/theme/_skins.scss` and `tokens/skins.css` must declare the
+#      same skin names, and each mirror skin's brand hex must appear in the
+#      matching SCSS block.
+#   3. Dangling-token audit: any fallback-less `var(--zer0-…)` reference in
+#      `_sass/` must be declared somewhere (tokens, includes, or JS).
+#
+#   ruby scripts/design-system-check.rb        # exit 1 + report on drift
+#
+# Runs in the `core` test suite (test/test_core.sh). Plain Ruby, no gems.
+# ---------------------------------------------------------------------------
+
+ROOT = File.expand_path('..', __dir__)
+
+PAIRS = {
+  '_sass/tokens/_color.scss'       => '_design-system/tokens/colors.css',
+  '_sass/tokens/_spacing.scss'     => '_design-system/tokens/spacing.css',
+  '_sass/tokens/_radius.scss'      => '_design-system/tokens/radius.css',
+  '_sass/tokens/_typography.scss'  => '_design-system/tokens/typography.css',
+  '_sass/tokens/_shadow.scss'      => '_design-system/tokens/shadows.css',
+  '_sass/tokens/_motion.scss'      => '_design-system/tokens/motion.css',
+  '_sass/tokens/_breakpoints.scss' => '_design-system/tokens/breakpoints.css',
+  '_sass/tokens/_layers.scss'      => '_design-system/tokens/layers.css'
+}.freeze
+
+SKIN_SCSS = '_sass/theme/_skins.scss'
+SKIN_CSS  = '_design-system/tokens/skins.css'
+
+def read(rel)
+  path = File.join(ROOT, rel)
+  abort "design-system-check: missing file #{rel}" unless File.file?(path)
+  File.read(path)
+end
+
+# Strip /* */ blocks, // line comments, and everything from the first @media on
+# (motion files re-declare durations under prefers-reduced-motion).
+def strip(text, scss:)
+  t = text.split('@media', 2).first
+  t = t.gsub(%r{/\*.*?\*/}m, '')
+  t = t.gsub(%r{(?:^|\s)//.*$}, '') if scss
+  t
+end
+
+# { '--zer0-foo' => 'raw value', ... } from declaration-position matches.
+def declarations(text)
+  text.scan(/(--zer0-[\w-]+)\s*:\s*([^;]+);/).each_with_object({}) do |(k, v), h|
+    h[k] ||= v.strip.gsub(/\s+/, ' ')
+  end
+end
+
+# All custom properties (any prefix) declared in the mirror's colors.css light
+# scope — the concrete primitives var() chains resolve against.
+def primitives
+  light = read(SKIN_CSS.sub('skins', 'colors')).split('[data-bs-theme="dark"]', 2).first
+  strip(light, scss: false).scan(/(--[\w-]+)\s*:\s*([^;]+);/)
+                           .each_with_object({}) { |(k, v), h| h[k] ||= v.strip.gsub(/\s+/, ' ') }
+end
+
+# Resolve a value that is entirely a var() wrapper: prefer the primitive's
+# concrete value, else the wrapper's own fallback. Inner var() references in
+# composite values (color-mix, rgba) are left as-is and compared literally.
+def resolve(value, prims, depth = 0)
+  v = value.strip.gsub(/\s+/, ' ')
+  return v if depth > 6
+
+  m = v.match(/\Avar\((--[\w-]+)(?:\s*,\s*(.+))?\)\z/)
+  return v unless m
+
+  name, fallback = m[1], m[2]
+  if prims.key?(name)
+    resolve(prims[name], prims, depth + 1)
+  elsif fallback
+    resolve(fallback, prims, depth + 1)
+  else
+    v
+  end
+end
+
+failures = []
+prims = primitives
+
+# --- 1. token parity per file pair -----------------------------------------
+PAIRS.each do |scss_rel, css_rel|
+  scss = declarations(strip(read(scss_rel), scss: true))
+  css  = declarations(strip(read(css_rel),  scss: false))
+
+  (scss.keys - css.keys).each { |k| failures << "#{css_rel}: missing #{k} (declared in #{scss_rel})" }
+  (css.keys - scss.keys).each { |k| failures << "#{scss_rel}: missing #{k} (declared in #{css_rel})" }
+
+  (scss.keys & css.keys).each do |k|
+    a = resolve(scss[k], prims)
+    b = resolve(css[k], prims)
+    failures << "#{k}: theme resolves to `#{a}` but mirror to `#{b}`" unless a == b
+  end
+end
+
+# Both motion files must keep the reduced-motion guard.
+[PAIRS.key('_design-system/tokens/motion.css'), '_design-system/tokens/motion.css'].each do |rel|
+  failures << "#{rel}: lost its prefers-reduced-motion guard" unless read(rel).include?('prefers-reduced-motion')
+end
+
+# --- 2. skins: same names, same brand hex ----------------------------------
+scss_skins_src = read(SKIN_SCSS)
+css_skins_src  = read(SKIN_CSS)
+scss_skins = scss_skins_src.scan(/\[data-theme-skin="(\w+)"\]/).flatten.uniq.sort
+css_skins  = css_skins_src.scan(/\[data-theme-skin="(\w+)"\]/).flatten.uniq.sort
+unless scss_skins == css_skins
+  failures << "skins differ: theme has #{scss_skins.join(', ')} but mirror has #{css_skins.join(', ')}"
+end
+
+(scss_skins & css_skins).each do |skin|
+  block = css_skins_src[/\[data-theme-skin="#{skin}"\]\s*\{.*?\}/m].to_s
+  hex = block[/--zer0-color-primary:\s*(#\h+)/, 1]
+  next unless hex
+
+  scss_block = scss_skins_src[/\[data-theme-skin="#{skin}"\]\s*\{.*?\}/m].to_s
+  unless scss_block.downcase.include?(hex.downcase)
+    failures << "skin #{skin}: mirror brand #{hex} not found in #{SKIN_SCSS}"
+  end
+end
+
+# --- 3. dangling-token audit ------------------------------------------------
+declared = Dir.glob(File.join(ROOT, '_sass/**/*.scss'))
+              .flat_map { |f| File.read(f).scan(/(--zer0-[\w-]+)\s*:/) }.flatten
+declared += Dir.glob(File.join(ROOT, '{_includes,_layouts}/**/*.html'))
+               .flat_map { |f| File.read(f).scan(/(--zer0-[\w-]+)\s*:/) }.flatten
+declared += Dir.glob(File.join(ROOT, 'assets/js/**/*.js')).flat_map do |f|
+  src = File.read(f)
+  src.scan(/setProperty\(\s*['"](--zer0-[\w-]+)/).flatten +
+    src.scan(/['"`](--zer0-[\w-]+)['"`:]/).flatten
+end
+declared = declared.uniq
+
+Dir.glob(File.join(ROOT, '_sass/**/*.scss')).sort.each do |f|
+  File.read(f).scan(/var\(\s*(--zer0-[\w-]+)\s*\)/).flatten.uniq.each do |token|
+    next if declared.include?(token)
+
+    failures << "#{f.sub("#{ROOT}/", '')}: references #{token} with no fallback, but it is never declared"
+  end
+end
+
+# --- report -----------------------------------------------------------------
+if failures.empty?
+  puts "design-system-check: OK — #{PAIRS.size} token file pairs, #{css_skins.size} skins, no dangling tokens"
+else
+  warn "design-system-check: #{failures.size} problem(s) — theme (_sass/tokens) and mirror (_design-system/tokens) have drifted:"
+  failures.each { |f| warn "  - #{f}" }
+  warn 'Fix the drift (see _design-system/SYNC.md), then re-run: ruby scripts/design-system-check.rb'
+  exit 1
+end

data/scripts/install/README.md

@@ -86,8 +86,11 @@ This installer runs on macOS's `/bin/bash` (3.2). Restrictions:
 # Local development
 ./scripts/bin/install help
 ./scripts/bin/install init . --profile blog --site-title "My Blog"
-./scripts/bin/install wizard . --ai
-./scripts/bin/install doctor .
+./scripts/bin/install init . --config zer0.install.yml     # config-file driven
+./scripts/bin/install wizard . --ai                        # Claude Code OAuth if available
+./scripts/bin/install wizard . --ai --ai-provider anthropic
+./scripts/bin/install suggest . "a docs site for a Rust CLI"
+./scripts/bin/install doctor .                             # shows the active AI provider
 ./scripts/bin/install diff .
 ./scripts/bin/install plan . --profile docs
 
@@ -110,17 +113,55 @@ curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/scripts/b
 3. Add template to `templates/config/` or `templates/pages/`
 4. List in the appropriate profile YAML under `templates/profiles/`
 
+## Config file layer
+
+Sites can persist installer choices in a small YAML file instead of re-typing flags. `config.sh` discovers and merges these (low→high precedence):
+
+1. `~/.config/zer0/install.yml` (user-global)
+2. `<target>/zer0.install.yml` (project-local)
+3. `<target>/.zer0/config.yml` (project-local, hidden)
+4. `$ZER0_CONFIG` / `--config FILE` (explicit — wins)
+
+The config layer sits between profile defaults and env/flag overrides:
+
+```
+defaults < profile < CONFIG FILE < env vars < CLI flags
+```
+
+Recognised keys (nested **or** flat/dotted both work): `profile`, `site.{title,description,author,email,url,timezone,locale}`, `github.{user,repo,pages_branch,enable_pages}`, `theme.{source,version}`, `deploy`, `agents`, `tasks`, `ai.provider`, `ai.model`. Example:
+
+```yaml
+profile: github-pages
+site:
+  title: "My Docs"
+deploy: [github-pages]
+ai:
+  provider: claude-cli      # auto | claude-cli | anthropic | openai | none
+```
+
+API keys are **never** read from config files — they stay in the environment.
+
 ## AI integration
 
 The AI path is a first-class citizen but never mandatory:
 
 - `ai_wizard_run` → interactive LLM spec generation
-- `ai_diagnose_run` → post-build error analysis  
-- `ai_suggest_run` → profile + deploy recommendation
+- `ai_diagnose_run` → post-build error analysis
+- `ai_suggest_run` → profile + deploy recommendation (also `install suggest`)
+
+All are guarded by the `ZER0_NO_AI=1` kill-switch and degrade gracefully to defaults or rule-based logic when AI is unavailable.
+
+### Providers (`ai/client.sh`)
+
+The client is multi-provider. `ZER0_AI_PROVIDER` (or config `ai.provider`, or `--ai-provider`) selects one; the default `auto` resolves in this order:
 
-All three are guarded by `ZER0_NO_AI=1` kill-switch and degrade gracefully to defaults or rule-based logic when AI is unavailable.
+| # | Provider     | Auth                                            | Notes |
+|---|--------------|-------------------------------------------------|-------|
+| 1 | `claude-cli` | the logged-in `claude` CLI (**Claude Code OAuth**) | Zero key handling — reuses `claude setup-token` / `claude login`. Preferred when the `claude` binary is on `PATH`. |
+| 2 | `anthropic`  | `CLAUDE_CODE_OAUTH_TOKEN` (OAuth) or `ANTHROPIC_API_KEY` | Anthropic Messages API over HTTPS. |
+| 3 | `openai`     | `OPENAI_API_KEY` (or `OPENAI_BASE_URL` for Azure/Ollama) | OpenAI-compatible `/chat/completions`. |
 
-To enable: set `OPENAI_API_KEY` (or `OPENAI_BASE_URL` for Azure/Ollama).
+Model is auto-defaulted per provider and overridable with `ZER0_AI_MODEL` / `--ai-model` (`ANTHROPIC_MODEL` / `OPENAI_MODEL` also honoured). Run `install doctor` to see which provider is active. All calls are single-attempt with a 30s timeout; user context is sanitized before it leaves the host.
 
 ## Deploy plugins