Page Template

#!/usr/bin/env python3
"""Orphan-page detector for static HTML mini-sites.

Walks every ``*.html`` under a given directory, parses ``<a href>`` links,
builds a directed reachability graph, and reports any HTML file not reachable
from the entry-point ``index.html``. Designed to complement Lychee, which
catches broken links but does not flag unreferenced files.

Usage::

    python scripts/check-orphan-pages.py docs/contractor-site/

Exit codes:
    0  No orphans (all HTML reachable from index.html)
    1  One or more orphan files detected
    2  Bad invocation (missing arg, no index.html, etc.)

Implementation notes:
    Pure stdlib only (html.parser) so it has no install footprint and works
    against any clean Python 3.10+ environment. Run-time on a 100-page site
    is well under a second.
"""

from __future__ import annotations

import argparse
import sys
from html.parser import HTMLParser
from pathlib import Path
from urllib.parse import urlparse


class _AnchorExtractor(HTMLParser):
    """Collect every ``href`` value from ``<a>`` tags in document order."""

    def __init__(self) -> None:
        super().__init__()
        self.hrefs: list[str] = []

    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
        if tag.lower() != "a":
            return
        for name, value in attrs:
            if name.lower() == "href" and value:
                self.hrefs.append(value)


def _is_local_html(href: str) -> bool:
    """True if href targets a local HTML file (not an absolute URL or anchor only)."""
    parsed = urlparse(href)
    if parsed.scheme in {"http", "https", "mailto", "tel", "javascript"}:
        return False
    path = parsed.path
    if not path:
        return False  # anchor-only ('#section') doesn't claim ownership of a file
    return path.endswith(".html") or path.endswith("/")


def _resolve(source: Path, href: str, root: Path) -> Path | None:
    """Resolve ``href`` (relative to ``source``) to an absolute path inside ``root``.

    Returns None if the resolved path escapes ``root`` or doesn't end in .html
    after directory-index normalization.
    """
    parsed = urlparse(href)
    raw_path = parsed.path or ""
    if raw_path.startswith("/"):
        # Treat absolute paths as rooted at site root
        target = (root / raw_path.lstrip("/")).resolve()
    else:
        target = (source.parent / raw_path).resolve()

    # Directory references default to /index.html
    if target.is_dir() or raw_path.endswith("/"):
        target = target / "index.html"

    try:
        target.relative_to(root.resolve())
    except ValueError:
        return None  # escaped the site root

    return target if target.suffix == ".html" else None


def _collect_html_files(root: Path) -> set[Path]:
    return {p.resolve() for p in root.rglob("*.html") if p.is_file()}


def _build_outgoing(html_files: set[Path], root: Path) -> dict[Path, set[Path]]:
    out: dict[Path, set[Path]] = {p: set() for p in html_files}
    for source in html_files:
        try:
            text = source.read_text(encoding="utf-8")
        except UnicodeDecodeError:
            text = source.read_text(encoding="utf-8", errors="replace")
        parser = _AnchorExtractor()
        parser.feed(text)
        for href in parser.hrefs:
            if not _is_local_html(href):
                continue
            target = _resolve(source, href, root)
            if target and target in html_files:
                out[source].add(target)
    return out


def _walk_reachable(
    entry: Path,
    outgoing: dict[Path, set[Path]],
) -> set[Path]:
    reachable: set[Path] = {entry}
    stack: list[Path] = [entry]
    while stack:
        node = stack.pop()
        for child in outgoing.get(node, ()):
            if child not in reachable:
                reachable.add(child)
                stack.append(child)
    return reachable


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
    parser.add_argument(
        "directory",
        type=Path,
        help="Site root containing index.html and other *.html pages",
    )
    parser.add_argument(
        "--entry",
        default="index.html",
        help="Entry file relative to <directory> (default: index.html)",
    )
    args = parser.parse_args()

    root = args.directory.resolve()
    if not root.is_dir():
        print(f"FATAL: {root} is not a directory", file=sys.stderr)
        return 2

    entry = (root / args.entry).resolve()
    if not entry.is_file():
        print(f"FATAL: entry file not found: {entry}", file=sys.stderr)
        return 2

    html_files = _collect_html_files(root)
    if not html_files:
        print(f"No HTML files under {root}", file=sys.stderr)
        return 0

    outgoing = _build_outgoing(html_files, root)
    reachable = _walk_reachable(entry, outgoing)
    orphans = sorted(html_files - reachable)

    print(f"Checked {len(html_files)} HTML file(s) under {root}")
    print(f"Entry: {entry.relative_to(root)}")
    print(f"Reachable: {len(reachable)}")

    if orphans:
        print(f"\nORPHAN PAGES ({len(orphans)}):")
        for o in orphans:
            print(f"  - {o.relative_to(root)}")
        print(
            "\nFix: add an <a href> from at least one reachable page, or "
            "delete the orphan file.",
            file=sys.stderr,
        )
        return 1

    print("\nOK — every HTML file is reachable from the entry page.")
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env bash
# install.sh — one-shot bootstrap for the html-showcase pipeline.
#
# Drops the three pipeline scripts (build-nav.py, check-orphan-pages.py,
# site.sh) into <repo>/scripts/, ensures **/.published.json is gitignored,
# and optionally seeds a starter site directory with index.html +
# overrides.css.example + lychee.toml.
#
# Idempotent: re-running with no changes is a no-op. Non-destructive:
# never overwrites an existing file unless --force is passed.
#
# Usage:
#   bash install.sh [--repo <path>] [--site <name>] [--force] [--check] [--hook]
#
#   --repo <path>   Target repo root (default: $PWD or `git rev-parse
#                   --show-toplevel` if invoked inside a git tree)
#   --site <name>   Also scaffold <repo>/<name>/ with starter HTML files
#                   (default: skip; pass e.g. `--site contractor-site`
#                   to seed one)
#   --force         Overwrite existing scripts/templates if they differ
#   --check         Preflight only: report what's already installed and
#                   what would be installed, exit 0 if everything is
#                   already in place, exit 10 if anything is missing.
#                   Pairs with the /html-showcase:setup skill.
#   --hook          Also install a pre-push git hook that regenerates the
#                   sitemap + Pagefind search index and rsyncs every
#                   tracked site dir to bigblack on `git push main`.
#                   Wires <repo>/.githooks/ via `git config
#                   core.hooksPath .githooks`. Non-blocking; failure
#                   never blocks the push.
#
# After install, the workflow is:
#   scripts/site.sh nav   <site-dir>   # regenerate sitemap + auto-nav
#   scripts/site.sh check <site-dir>   # nav + lychee + orphan-page
#   scripts/site.sh push  <site-dir>   # nav + check + rsync to bigblack

set -euo pipefail

# ----------------------------------------------------------------------
# Resolve the source skill directory regardless of how install.sh was
# invoked (via $CLAUDE_PLUGIN_ROOT, via a clone of cc-skills, or via a
# direct path).
#
# Use $0 (works under both bash and zsh) instead of BASH_SOURCE[0]
# (bash-only) so users who accidentally run `zsh install.sh` still get
# a working bootstrap.
# ----------------------------------------------------------------------
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
SCRIPTS_SRC="$SKILL_DIR/scripts"
TEMPLATES_SRC="$SKILL_DIR/templates"

# ----------------------------------------------------------------------
# Parse args
# ----------------------------------------------------------------------
REPO=""
SITE=""
FORCE=0
CHECK_ONLY=0
INSTALL_HOOK=0

while [[ $# -gt 0 ]]; do
  case "$1" in
    --repo)  REPO="$2";  shift 2 ;;
    --site)  SITE="$2";  shift 2 ;;
    --force) FORCE=1;    shift ;;
    --check) CHECK_ONLY=1; shift ;;
    --hook)  INSTALL_HOOK=1; shift ;;
    -h|--help)
      sed -n '2,/^$/p' "$0" | sed 's/^# *//'
      exit 0 ;;
    *)
      echo "unknown flag: $1 (use --help)" >&2
      exit 2 ;;
  esac
done

# Resolve repo root — prefer git, fall back to PWD.
if [[ -z "$REPO" ]]; then
  if REPO="$(git rev-parse --show-toplevel 2>/dev/null)"; then
    :
  else
    REPO="$PWD"
  fi
fi
REPO="$(cd "$REPO" && pwd)"

if [[ ! -d "$REPO" ]]; then
  echo "✗ target repo does not exist: $REPO" >&2
  exit 1
fi

# ----------------------------------------------------------------------
# Toolchain preflight: python3 must be ≥ 3.10 (build-nav.py uses
# pathlib's walk_up=True on 3.12+ with a 3.10/3.11 fallback). Failing
# loudly here beats a cryptic TypeError on first nav rebuild.
# ----------------------------------------------------------------------
if command -v python3 >/dev/null 2>&1; then
  if ! python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)' 2>/dev/null; then
    py_ver="$(python3 --version 2>&1 || echo unknown)"
    echo "✗ python3 is too old: ${py_ver}. Need Python 3.10 or newer." >&2
    echo "  Install: brew install python@3.14  (or: mise use python@3.14)" >&2
    exit 1
  fi
else
  echo "✗ python3 not on PATH. Install: brew install python@3.14" >&2
  exit 1
fi

if [[ $CHECK_ONLY -eq 1 ]]; then
  echo "→ preflight check for $REPO"
else
  echo "→ installing html-showcase pipeline into $REPO"
fi

# Tracks "missing or out-of-date" count for --check exit code.
MISSING_COUNT=0

# ----------------------------------------------------------------------
# Helper: copy a file unless it already exists with identical content.
# Honors --force for a clean overwrite. Under --check, never copies —
# only reports.
# ----------------------------------------------------------------------
copy_if_new() {
  local src="$1" dst="$2" label="$3"
  if [[ ! -f "$src" ]]; then
    echo "  ✗ source missing: $src" >&2
    return 1
  fi
  if [[ -f "$dst" ]]; then
    if cmp -s "$src" "$dst"; then
      echo "  = $label (unchanged)"
      return 0
    fi
    if [[ $CHECK_ONLY -eq 1 ]]; then
      echo "  ✗ $label differs from canonical (would update on install)"
      MISSING_COUNT=$((MISSING_COUNT + 1))
      return 0
    fi
    if [[ $FORCE -ne 1 ]]; then
      echo "  ⚠ $label exists and differs — pass --force to overwrite"
      return 0
    fi
  elif [[ $CHECK_ONLY -eq 1 ]]; then
    echo "  ✗ $label not installed"
    MISSING_COUNT=$((MISSING_COUNT + 1))
    return 0
  fi
  # Explicit 0755 — don't trust the source file's bits (the user might
  # have a tight umask or a checkout with stripped exec bits) and don't
  # trust stat to be portable across filesystems.
  install -m 0755 "$src" "$dst"
  echo "  ✓ $label"
}

# ----------------------------------------------------------------------
# 1. Pipeline scripts → <repo>/scripts/
# ----------------------------------------------------------------------
[[ $CHECK_ONLY -eq 1 ]] || mkdir -p "$REPO/scripts"
copy_if_new "$SCRIPTS_SRC/build-nav.py"         "$REPO/scripts/build-nav.py"         "scripts/build-nav.py"
copy_if_new "$SCRIPTS_SRC/check-orphan-pages.py" "$REPO/scripts/check-orphan-pages.py" "scripts/check-orphan-pages.py"
copy_if_new "$SCRIPTS_SRC/site.sh"              "$REPO/scripts/site.sh"              "scripts/site.sh"

# ----------------------------------------------------------------------
# 2. .gitignore — ensure provenance + Pagefind index aren't committed.
#
# Two patterns:
#   **/.published.json   — per-push provenance stamp (regenerated each push)
#   **/pagefind/         — Pagefind binary's static index (regenerated each
#                          nav build; committing it causes diff churn when
#                          team members have different pagefind versions)
#
# We use a BOM-aware variant of grep -qxF: if a user's .gitignore was
# saved with a UTF-8 BOM, `grep -qxF` against the raw line "**/foo" can
# fail-to-find an entry that's actually present. Strip BOM via sed first.
# ----------------------------------------------------------------------
GITIGNORE="$REPO/.gitignore"
PUBLISHED_PATTERN='**/.published.json'
PAGEFIND_PATTERN='**/pagefind/'

# Test for a pattern's presence in .gitignore, BOM-tolerant.
gitignore_has() {
  local pat="$1"
  [[ -f "$GITIGNORE" ]] || return 1
  sed '1s/^\xEF\xBB\xBF//' "$GITIGNORE" | grep -qxF "$pat"
}

# Single-pass append: collect all missing patterns, write them all in
# one append operation. Atomic enough that a SIGINT between the first
# and second append doesn't leave the repo in a "I already added one
# pattern, re-run won't add the second" state.
missing_patterns=()
missing_comments=()
for pair in \
    "$PUBLISHED_PATTERN|published-page provenance manifests" \
    "$PAGEFIND_PATTERN|Pagefind static search index (regenerated per nav build)"
do
  pat="${pair%%|*}"
  comment="${pair#*|}"
  if [[ ! -f "$GITIGNORE" ]] || ! gitignore_has "$pat"; then
    missing_patterns+=("$pat")
    missing_comments+=("$comment")
  else
    echo "  = .gitignore already lists $pat"
  fi
done

if [[ ${#missing_patterns[@]} -gt 0 ]]; then
  if [[ $CHECK_ONLY -eq 1 ]]; then
    for pat in "${missing_patterns[@]}"; do
      echo "  ✗ .gitignore missing entry $pat"
      MISSING_COUNT=$((MISSING_COUNT + 1))
    done
  else
    # Build the full block in memory FIRST, then write in one shot.
    # Resolving "does the file exist?" BEFORE opening the append
    # redirect avoids the shellcheck SC2094 read+write-in-same-pipeline
    # warning, and also lets us either-write-everything-or-nothing on
    # SIGINT (no half-applied state across the two patterns).
    gitignore_existed=0
    [[ -f "$GITIGNORE" ]] && gitignore_existed=1
    block=""
    if [[ $gitignore_existed -eq 1 ]]; then
      block=$'\n'
    fi
    hash_tag='#'
    for i in "${!missing_patterns[@]}"; do
      block+="${hash_tag} html-showcase: ${missing_comments[$i]}"$'\n'
      block+="${missing_patterns[$i]}"$'\n'
    done
    printf '%s' "$block" >> "$GITIGNORE"
    for pat in "${missing_patterns[@]}"; do
      echo "  ✓ appended $pat to .gitignore"
    done
  fi
fi

# If `pagefind/` is already TRACKED by git (committed before being
# gitignored), gitignoring it doesn't untrack the existing copies. The
# user will keep seeing diff churn every time the index regenerates.
# Surfaced in BOTH --check and install modes so users running --check
# (the most common upgrade pre-flight) actually see the warning.
#
# Pathspec note: `**/pagefind/` is gitignore-glob syntax, NOT git
# pathspec syntax. ls-files needs a real pathspec — `*pagefind/*`
# matches any path containing pagefind/ (verified empirically; the
# previous --error-unmatch with gitignore syntax never matched).
if command -v git >/dev/null 2>&1; then
  if git -C "$REPO" rev-parse --git-dir >/dev/null 2>&1; then
    tracked_pagefind="$(git -C "$REPO" ls-files '*pagefind/*' 2>/dev/null | head -1)"
    if [[ -n "$tracked_pagefind" ]]; then
      echo "  ⚠ pagefind/ is already tracked by git (e.g., $tracked_pagefind)." >&2
      echo "    To stop committing the index, run:" >&2
      echo "      git -C $REPO rm -r --cached '*pagefind/*' && git commit -m 'untrack pagefind index'" >&2
      [[ $CHECK_ONLY -eq 1 ]] && MISSING_COUNT=$((MISSING_COUNT + 1))
    fi
  fi
fi

# ----------------------------------------------------------------------
# 3. (optional) Seed a starter site dir with index.html + overrides + lychee
# ----------------------------------------------------------------------
if [[ -n "$SITE" ]]; then
  SITE_DIR="$REPO/$SITE"
  [[ $CHECK_ONLY -eq 1 ]] || mkdir -p "$SITE_DIR"
  echo "→ seeding site directory: $SITE_DIR"
  copy_if_new "$TEMPLATES_SRC/index.html"             "$SITE_DIR/index.html"        "$SITE/index.html"
  copy_if_new "$TEMPLATES_SRC/overrides.css.example"  "$SITE_DIR/overrides.css"     "$SITE/overrides.css"
  copy_if_new "$TEMPLATES_SRC/lychee.toml"            "$SITE_DIR/lychee.toml"       "$SITE/lychee.toml"
  if [[ $CHECK_ONLY -ne 1 ]]; then
    echo "  → fill {{ PLACEHOLDERS }} in $SITE/index.html, then:"
    echo "      python3 $REPO/scripts/build-nav.py --root $SITE_DIR"
  fi
fi

# ----------------------------------------------------------------------
# 3.5. Pre-push hook validation/install.
#
# When --hook is passed: install/refresh the hook in .githooks/pre-push
# and wire core.hooksPath. When --check is passed AND a hook is already
# present at .githooks/pre-push, validate it even WITHOUT --hook so a
# user upgrading the plugin can detect a stale committed hook without
# having to remember to add --hook each time.
# ----------------------------------------------------------------------
EXISTING_HOOK="$REPO/.githooks/pre-push"
if [[ $INSTALL_HOOK -ne 1 && $CHECK_ONLY -eq 1 && -f "$EXISTING_HOOK" ]]; then
  HOOK_SRC="$SCRIPTS_SRC/pre-push.template"
  if [[ -f "$HOOK_SRC" ]] && ! cmp -s "$HOOK_SRC" "$EXISTING_HOOK"; then
    echo "→ pre-push hook present at .githooks/pre-push but differs from canonical:"
    echo "  ✗ .githooks/pre-push is stale (would update on install --hook --force)"
    MISSING_COUNT=$((MISSING_COUNT + 1))
  fi
fi

if [[ $INSTALL_HOOK -eq 1 ]]; then
  HOOK_SRC="$SCRIPTS_SRC/pre-push.template"
  HOOK_DST="$REPO/.githooks/pre-push"
  echo "→ installing pre-push hook: $HOOK_DST"
  if [[ ! -f "$HOOK_SRC" ]]; then
    echo "  ✗ template missing at $HOOK_SRC" >&2
    [[ $CHECK_ONLY -eq 1 ]] && MISSING_COUNT=$((MISSING_COUNT + 1))
  else
    if [[ -f "$HOOK_DST" ]] && cmp -s "$HOOK_SRC" "$HOOK_DST"; then
      echo "  = .githooks/pre-push (unchanged)"
    elif [[ -f "$HOOK_DST" && $FORCE -ne 1 && $CHECK_ONLY -ne 1 ]]; then
      echo "  ⚠ .githooks/pre-push exists and differs — pass --force to overwrite"
    elif [[ $CHECK_ONLY -eq 1 ]]; then
      if [[ -f "$HOOK_DST" ]]; then
        echo "  ✗ .githooks/pre-push differs from canonical (would update on install)"
      else
        echo "  ✗ .githooks/pre-push not installed"
      fi
      MISSING_COUNT=$((MISSING_COUNT + 1))
    else
      mkdir -p "$REPO/.githooks"
      install -m 755 "$HOOK_SRC" "$HOOK_DST"
      echo "  ✓ .githooks/pre-push"
    fi
  fi
  # Wire core.hooksPath so the hook actually fires. Idempotent and
  # collision-aware: if another hook engine (Husky, lefthook, pre-commit)
  # already pointed core.hooksPath somewhere else, refuse to clobber it
  # silently. The user gets a clear error and can pass --force to
  # override after they've decided whether to migrate.
  if [[ $CHECK_ONLY -ne 1 ]]; then
    # `--local` reads ONLY the repo's .git/config, NOT global/system. A
    # global `core.hooksPath = .husky` (set in ~/.config/git/config) is
    # the user's environment choice and shouldn't false-positive a
    # collision warning for every repo they install into.
    current_path="$(git -C "$REPO" config --local --get core.hooksPath 2>/dev/null || echo '')"
    if [[ "$current_path" == ".githooks" ]]; then
      echo "  = git config core.hooksPath already set to .githooks"
    elif [[ -n "$current_path" ]]; then
      if [[ $FORCE -eq 1 ]]; then
        git -C "$REPO" config core.hooksPath .githooks
        echo "  ✓ git config core.hooksPath = .githooks (overrode '$current_path' via --force)"
      else
        echo "  ⚠ core.hooksPath is already set to '$current_path' (Husky/lefthook/pre-commit?)" >&2
        echo "    Refusing to override silently. Options:" >&2
        echo "      • Re-run with --force to set core.hooksPath = .githooks" >&2
        echo "      • Manually merge: copy $REPO/.githooks/pre-push into '$current_path/pre-push'" >&2
        echo "      • Skip the hook: use scripts/site.sh push manually instead" >&2
        exit 3
      fi
    else
      git -C "$REPO" config core.hooksPath .githooks
      echo "  ✓ git config core.hooksPath = .githooks"
    fi
  fi
fi

# ----------------------------------------------------------------------
# 4. Summary
# ----------------------------------------------------------------------
if [[ $CHECK_ONLY -eq 1 ]]; then
  if [[ $MISSING_COUNT -eq 0 ]]; then
    echo
    echo "✓ everything in place — no install needed"
    exit 0
  fi
  echo
  echo "$MISSING_COUNT item(s) need installation. Re-run without --check to apply."
  exit 10
fi

cat <<EOF

✓ install complete

Next steps:
  1. (Optional) Add shorthand mise tasks: drop a .mise/tasks/site.toml that
     wraps scripts/site.sh — see references/publishing.md for an example.
  2. Author HTML files in <site-dir>/ and any <site-dir>/<section-slug>/.
     Each subdir of the site root that contains *.html becomes a "section".
  3. Build the sitemap + auto-nav rail:
       python3 scripts/build-nav.py --root <site-dir>
     or, equivalently:
       scripts/site.sh nav <site-dir>
  4. Validate locally:
       scripts/site.sh check <site-dir>
  5. Publish to bigblack via Tailscale:
       scripts/site.sh push <site-dir>

Skill: html-showcase:page-template (cc-skills marketplace)
SSoT for the architecture: $SKILL_DIR/SKILL.md
EOF

#!/usr/bin/env bash
# pre-push hook — regenerate sitemap + search index and resync sites to
# bigblack via Tailscale before pushing to the remote.
#
# Installed by: bash <plugin>/skills/page-template/scripts/install.sh --hook
# Activated when: $REPO_ROOT/.githooks is wired via `git config
#                 core.hooksPath .githooks` (install.sh sets this for you).
#
# What runs on `git push <remote> main`:
#   1. For each tracked site dir (env HTMLSHOWCASE_SITES, or
#      auto-detected by finding directories that contain a
#      site-map.html generated by build-nav.py):
#        a. scripts/site.sh nav <site-dir>     ← rebuild rail + search index
#        b. scripts/site.sh push <site-dir>    ← rsync to bigblack
#   2. The actual `git push` continues regardless of hook status —
#      sync failure must never block the push (matches opendeviationbar
#      pattern: bigblack is a delivery surface, not a quality gate).
#
# Skip knobs:
#   NO_HTMLSHOWCASE_HOOK=1     skip everything (hook is a no-op)
#   NO_HTMLSHOWCASE_SYNC=1     run nav + search but skip rsync
#   NO_HTMLSHOWCASE_SEARCH=1   skip the pagefind regen step
#   HTMLSHOWCASE_SITES="…"     explicit space-separated site dirs, overrides
#                              auto-detection (relative to repo root)
#
# git push --dry-run still triggers this hook (git can't tell us about
# --dry-run via stdin). To preview a push without rsync:
#   NO_HTMLSHOWCASE_SYNC=1 git push --dry-run …
#
# Non-blocking: every failure path logs a warning and exits 0. Errors
# from rsync ARE surfaced to stderr so the user sees what went wrong;
# only the hook's exit status is forced to 0.

set -uo pipefail

if [[ "${NO_HTMLSHOWCASE_HOOK:-0}" == "1" ]]; then
    echo "[html-showcase] hook skipped (NO_HTMLSHOWCASE_HOOK=1)."
    exit 0
fi

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SITE_SH="${REPO_ROOT}/scripts/site.sh"

if [[ ! -x "$SITE_SH" ]]; then
    echo "[html-showcase] scripts/site.sh not found — hook is a no-op." >&2
    exit 0
fi

# Detect whether main is in the push set. The pre-push hook receives ref
# pairs on stdin: "<local_ref> <local_oid> <remote_ref> <remote_oid>".
# Both refs must be main/master so a `git push origin HEAD:main` from a
# feature branch doesn't accidentally publish the feature branch's
# state. (Caught by the edge-case audit; HIGH-severity finding.)
pushing_main=0
while IFS=' ' read -r local_ref _local_oid remote_ref _remote_oid; do
    local_main=0
    remote_main=0
    case "${local_ref:-}" in
        refs/heads/main|refs/heads/master) local_main=1 ;;
    esac
    case "${remote_ref:-}" in
        refs/heads/main|refs/heads/master) remote_main=1 ;;
    esac
    if [[ "$local_main" -eq 1 && "$remote_main" -eq 1 ]]; then
        pushing_main=1
        break
    fi
done

if [[ "${pushing_main}" -eq 0 ]]; then
    # Silent exit was confusing (round-3 audit: user pushes a feature
    # branch and sees no [html-showcase] output, can't tell if hook ran).
    # One-line log makes it explicit that the skip was intentional.
    echo "[html-showcase] skipping nav rebuild + rsync (push is not to main/master)"
    exit 0
fi

# Resolve which site dirs to process. Two modes:
#   1. Explicit list via $HTMLSHOWCASE_SITES (space-separated relative paths)
#   2. Auto-detect: any directory under REPO_ROOT that contains a
#      site-map.html generated by build-nav.py (we look for the marker).
sites=()
if [[ -n "${HTMLSHOWCASE_SITES:-}" ]]; then
    # shellcheck disable=SC2206  # word-split env var on purpose
    sites=($HTMLSHOWCASE_SITES)
else
    while IFS= read -r site_map; do
        # Each found site-map.html implies the directory containing it
        # is a site-root. Prune list covers:
        #   - VCS / package manager state: .git, node_modules
        #   - Generated artifacts: pagefind, dist, build, .next, .nuxt
        #   - Hook engines and Python venvs that might have stray HTML:
        #     .husky, .venv, venv
        site_dir="$(dirname "$site_map")"
        sites+=("${site_dir#${REPO_ROOT}/}")
    done < <(
        find "$REPO_ROOT" \
            -type d \( \
                -name node_modules -o -name .git -o -name pagefind \
                -o -name .husky -o -name .venv -o -name venv \
                -o -name dist -o -name build \
                -o -name .next -o -name .nuxt \
            \) -prune -o \
            -type f -name 'site-map.html' -print 2>/dev/null
    )
fi

if [[ "${#sites[@]}" -eq 0 ]]; then
    echo "[html-showcase] no site dirs found (looked for any dir containing site-map.html)."
    exit 0
fi

echo "[html-showcase] processing ${#sites[@]} site dir(s): ${sites[*]}"

for site in "${sites[@]}"; do
    site_path="${REPO_ROOT}/${site}"
    if [[ ! -d "$site_path" ]]; then
        echo "[html-showcase]   ⚠ skipping $site (not a directory)" >&2
        continue
    fi
    echo "[html-showcase] → $site"

    # nav rebuild — pass through the search-skip flag so the user's
    # NO_HTMLSHOWCASE_SEARCH=1 actually does what it says. (Earlier
    # version of this hook had two identical branches; caught by the
    # edge-case audit.)
    nav_args=("nav" "$site_path")
    if [[ "${NO_HTMLSHOWCASE_SEARCH:-0}" == "1" ]]; then
        nav_args+=("--skip-search")
    fi
    bash "$SITE_SH" "${nav_args[@]}" 2>&1 | sed 's/^/[html-showcase]   /' || \
        echo "[html-showcase]   ⚠ nav rebuild failed for $site" >&2

    if [[ "${NO_HTMLSHOWCASE_SYNC:-0}" == "1" ]]; then
        echo "[html-showcase]   skip rsync (NO_HTMLSHOWCASE_SYNC=1)"
        continue
    fi

    # Capture the actual push exit code via PIPESTATUS so SSH/rsync
    # failures surface to the user. The sed pipe was previously
    # swallowing them, leaving "publish succeeded" UX even when bigblack
    # rejected the connection.
    bash "$SITE_SH" push "$site_path" 2>&1 | sed 's/^/[html-showcase]   /'
    push_status=${PIPESTATUS[0]}
    if [[ "$push_status" -ne 0 ]]; then
        echo "[html-showcase]   ⚠ push FAILED (exit $push_status) for $site — your local changes still pushed to git, but the live site at bigblack was NOT updated." >&2
        echo "[html-showcase]     To retry manually:  bash $SITE_SH push $site_path" >&2
    fi
done

# Always exit 0 — sync failure must never block git push.
exit 0

#!/usr/bin/env bash
# site.sh — publish a static HTML directory to bigblack via Tailscale.
# Modeled on scripts/blob.sh from opendeviationbar-patterns. Adapt freely
# into other repos: copy this file, copy .mise/tasks/site.toml, copy
# scripts/check-orphan-pages.py, and you're done.
#
# Subcommands:
#   nav <local-dir>         Regenerate site-map.html + auto-nav rail + search index
#   search <local-dir>      Rebuild Pagefind search index only (no nav rebuild)
#   push <local-dir>        Build nav + validate + rsync to bigblack:~/sites/<project>/<page>/
#   check <local-dir>       Build nav + validate only (lychee + orphan-page detector)
#   url <local-dir>         Print the URL where <local-dir> would publish to
#   list                    List all published projects/pages on bigblack
#   unpublish <local-dir>   Remove the page from bigblack (asks for confirmation)
#
# URL format:
#   https://bigblack.tail0f299b.ts.net:8448/<project>/<page>/
#     <project>  derived from `git remote get-url origin` basename (or
#                $SITE_PROJECT_NAME override)
#     <page>     basename of <local-dir>
#
# Gate: every push runs lychee + orphan-page check FIRST. If either fails,
# nothing reaches bigblack. The validation is the only gate — there is no
# semantic-release here. Push-side gating, by design.

set -euo pipefail

# Repo detection: prefer git toplevel; fall back to PWD so site.sh works
# in non-git directories too (e.g. a one-off site assembled in /tmp).
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
BIGBLACK_SSH="${SITE_BIGBLACK_SSH:-bigblack}"
BIGBLACK_ROOT="${SITE_BIGBLACK_ROOT:-/home/tca/sites}"
SERVER_BASE_URL="${SITE_BASE_URL:-https://bigblack.tail0f299b.ts.net:8448}"

# Project namespace: from env or git remote
project_name() {
  if [[ -n "${SITE_PROJECT_NAME:-}" ]]; then
    echo "$SITE_PROJECT_NAME"
    return
  fi
  local remote
  remote="$(git -C "$REPO_ROOT" remote get-url origin 2>/dev/null || true)"
  if [[ -z "$remote" ]]; then
    basename "$REPO_ROOT"
    return
  fi
  basename "$remote" .git
}

# Page namespace: basename of local dir
page_name() {
  local local_dir="$1"
  basename "$(cd "$local_dir" && pwd)"
}

# Resolve the URL where a local dir publishes to
build_url() {
  local local_dir="$1"
  local project page
  project="$(project_name)"
  page="$(page_name "$local_dir")"
  echo "$SERVER_BASE_URL/$project/$page/"
}

# Resolve the bigblack remote path
build_remote_path() {
  local local_dir="$1"
  local project page
  project="$(project_name)"
  page="$(page_name "$local_dir")"
  echo "$BIGBLACK_ROOT/$project/$page"
}

# require <command> [install-hint]
# Aborts with a friendly error + brew/install hint when the command is missing.
require() {
  local cmd="$1" hint="${2:-}"
  if ! command -v "$cmd" >/dev/null 2>&1; then
    echo "✗ missing: $cmd" >&2
    [[ -n "$hint" ]] && echo "  Install: $hint" >&2
    exit 1
  fi
}

# Resolve build-nav.py: prefer scripts/build-nav.py in the consuming repo;
# fall back to the canonical copy that ships with this skill so a repo can
# call site.sh before it has copied the script in. Resolution order:
#   1. <repo>/scripts/build-nav.py
#   2. $CLAUDE_PLUGIN_ROOT/skills/page-template/scripts/build-nav.py
#      (set automatically by Claude Code when the skill is invoked)
#   3. Canonical install path: ~/.claude/plugins/marketplaces/cc-skills/...
resolve_build_nav() {
  if [[ -f "$REPO_ROOT/scripts/build-nav.py" ]]; then
    echo "$REPO_ROOT/scripts/build-nav.py"
    return
  fi
  local candidate
  for candidate in \
    "${CLAUDE_PLUGIN_ROOT:-}/skills/page-template/scripts/build-nav.py" \
    "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/html-showcase/skills/page-template/scripts/build-nav.py"
  do
    if [[ -n "$candidate" && -f "$candidate" ]]; then
      echo "$candidate"
      return
    fi
  done
  echo ""
}

cmd_nav() {
  # Accepts: <local-dir> [--skip-search]
  # The --skip-search flag is the wired-up consumer for the
  # NO_HTMLSHOWCASE_SEARCH=1 env knob in pre-push.template.
  local local_dir=""
  local skip_search=0
  while [[ $# -gt 0 ]]; do
    case "$1" in
      --skip-search) skip_search=1; shift ;;
      *) local_dir="$1"; shift ;;
    esac
  done
  [[ -n "$local_dir" ]] || { echo "usage: site.sh nav <local-dir> [--skip-search]" >&2; exit 1; }
  [[ -d "$local_dir" ]] || { echo "not a directory: $local_dir" >&2; exit 1; }
  local build_nav
  build_nav="$(resolve_build_nav)"
  if [[ -z "$build_nav" ]]; then
    echo "✗ build-nav.py not found." >&2
    echo "  Easiest fix: invoke /html-showcase:setup from Claude Code." >&2
    echo "  Manual fix:  bash \$CLAUDE_PLUGIN_ROOT/skills/page-template/scripts/install.sh" >&2
    exit 1
  fi
  echo "→ regenerating site-map + auto-nav for $local_dir"
  python3 "$build_nav" --root "$local_dir"
  if [[ $skip_search -eq 1 ]]; then
    echo "  (skipping search-index rebuild via --skip-search)"
  else
    # Always re-build the search index too — search is a default
    # feature, not an opt-in. cmd_search degrades gracefully if pagefind
    # is missing.
    cmd_search "$local_dir"
  fi
}

# pagefind is fetched separately (Rust single-binary release). Resolution
# order: $PAGEFIND_BIN, then $HOME/.local/bin/pagefind, then PATH lookup.
resolve_pagefind() {
  if [[ -n "${PAGEFIND_BIN:-}" && -x "$PAGEFIND_BIN" ]]; then
    echo "$PAGEFIND_BIN"
    return
  fi
  if [[ -x "$HOME/.local/bin/pagefind" ]]; then
    echo "$HOME/.local/bin/pagefind"
    return
  fi
  command -v pagefind 2>/dev/null || echo ""
}

cmd_search() {
  local local_dir="${1:?search <local-dir>}"
  [[ -d "$local_dir" ]] || { echo "not a directory: $local_dir" >&2; exit 1; }
  local pagefind
  pagefind="$(resolve_pagefind)"
  if [[ -z "$pagefind" ]]; then
    # Search is a default feature, but a missing binary should NOT block
    # the publish flow. Warn loudly and continue with whatever index is
    # already at <local-dir>/pagefind/ (or none, in which case the search
    # box renders inert until the user installs pagefind and re-runs).
    echo "⚠ pagefind not found — skipping search-index rebuild." >&2
    echo "  Install: brew install pagefind" >&2
    echo "  (or:     curl -fsSL https://github.com/CloudCannon/pagefind/releases/latest \\" >&2
    echo "             | … see https://pagefind.app/docs/installation/ )" >&2
    return 0
  fi
  # Sanity-check the binary actually runs before invoking it. ABI
  # mismatches (e.g., user upgraded macOS 13→15, or downloaded the
  # arm64 binary on an Intel Mac) would otherwise show up as a buried
  # "killed" message swallowed by our grep filter downstream.
  if ! "$pagefind" --version >/dev/null 2>&1; then
    echo "⚠ pagefind binary at $pagefind failed --version check." >&2
    echo "  Likely cause: architecture mismatch or corrupted download." >&2
    echo "  Reinstall: brew reinstall pagefind  (or rm $pagefind and re-fetch)" >&2
    return 0
  fi
  echo "→ rebuilding Pagefind search index for $local_dir"
  # Pre-clean any stale or half-built index from a previous killed run.
  # Without this, a SIGINT mid-pagefind leaves orphan chunks that the
  # next run won't auto-overwrite — bigblack would serve a half-broken
  # search until the user noticed and intervened.
  #
  # SYMLINK GUARD: refuse to follow a symlinked pagefind/ — `rm -rf`
  # on a symlink-to-directory deletes the TARGET's contents, not the
  # link. If a user symlinked pagefind/ to a shared cache outside the
  # site root, that cache would be wiped on every nav rebuild. (Caught
  # by the round-3 adversarial audit.)
  pf_dir="${local_dir%/}/pagefind"
  if [[ -L "$pf_dir" ]]; then
    echo "✗ $pf_dir is a symlink — refusing to rm -rf (would delete the link's target)." >&2
    echo "  Resolve manually: replace the symlink with a real directory before running search." >&2
    return 1
  fi
  rm -rf "$pf_dir"
  if ! "$pagefind" --site "${local_dir%/}" 2>&1 | grep -E '(Indexed|Finished|error|Error)'; then
    : # captured output already piped
  fi
  # Sanity: pagefind didn't write its UI assets → search will 404.
  if [[ ! -f "${local_dir%/}/pagefind/pagefind-ui.js" ]]; then
    echo "⚠ pagefind ran but didn't produce pagefind-ui.js — index may be incomplete." >&2
    return 1
  fi
}

cmd_check() {
  local local_dir="${1:?check <local-dir>}"
  [[ -d "$local_dir" ]] || { echo "not a directory: $local_dir" >&2; exit 1; }

  # Always regenerate nav before validating — sitemap is the SSoT for the
  # page graph, and lychee/orphan-check both depend on it being fresh.
  cmd_nav "$local_dir"

  echo "→ validating $local_dir"

  # Lychee link check.
  # Disable pipefail for the lychee pipe: a non-zero lychee exit (broken
  # links) interacts with `set -e` to abort the whole script BEFORE we
  # reach the if-block that prints remediation hints. By dropping
  # pipefail just for this pipe, we capture the exit code via
  # PIPESTATUS and print our own actionable diagnosis.
  require lychee "brew install lychee  (or: cargo install lychee)"
  local lychee_config="$local_dir/lychee.toml"
  local lychee_status=0
  set +o pipefail
  if [[ -f "$lychee_config" ]]; then
    echo "  lychee (config: $lychee_config)"
    lychee --config "$lychee_config" "$local_dir"/**/*.html 2>&1 | tail -20
  else
    echo "  lychee (no config; using defaults)"
    lychee "$local_dir"/**/*.html 2>&1 | tail -20
  fi
  lychee_status=${PIPESTATUS[0]}
  set -o pipefail
  if [[ $lychee_status -ne 0 ]]; then
    echo "✗ lychee found broken links — aborting" >&2
    echo "  Review the report above, fix the offending URLs / file paths," >&2
    echo "  then re-run:  scripts/site.sh check $local_dir" >&2
    echo "  (To allowlist a host, add it to the [exclude] section of $local_dir/lychee.toml.)" >&2
    exit 1
  fi

  # Orphan page detector
  if [[ -f "$REPO_ROOT/scripts/check-orphan-pages.py" ]]; then
    echo "  orphan-page check"
    python3 "$REPO_ROOT/scripts/check-orphan-pages.py" "$local_dir"
  else
    echo "  (skipped: scripts/check-orphan-pages.py not found)"
  fi

  echo "✓ validation passed"
}

cmd_push() {
  local local_dir="${1:?push <local-dir>}"
  [[ -d "$local_dir" ]] || { echo "not a directory: $local_dir" >&2; exit 1; }

  # 1. Validate first — push-side gate
  cmd_check "$local_dir"

  # 2. Compute provenance values (write the file ONLY after rsync
  # succeeds; otherwise a torn rsync would leave a `.published.json`
  # claiming the publish completed when bigblack was actually mid-write).
  local commit_sha timestamp project page url remote_path source_repo dirty
  commit_sha="$(git -C "$REPO_ROOT" rev-parse --short=12 HEAD 2>/dev/null || echo unknown)"
  dirty=""
  if ! git -C "$REPO_ROOT" diff --quiet -- "$local_dir" 2>/dev/null; then
    dirty="-dirty"
  fi
  timestamp="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
  project="$(project_name)"
  page="$(page_name "$local_dir")"
  url="$(build_url "$local_dir")"
  remote_path="$(build_remote_path "$local_dir")"
  source_repo="$(git -C "$REPO_ROOT" remote get-url origin 2>/dev/null || echo unknown)"

  # 3. Rsync to bigblack — abort on SSH or rsync failure BEFORE stamping
  # provenance. A failure here means the live site wasn't updated.
  #
  # The default $BIGBLACK_SSH (`bigblack`) resolves via Tailscale
  # MagicDNS. If Tailscale isn't running, the SSH attempt will fail
  # with a name-resolution error after a brief delay. The post-failure
  # message below mentions Tailscale explicitly so the user knows
  # what's missing rather than chasing SSH-key debug paths.
  echo "→ rsync $local_dir/ → $BIGBLACK_SSH:$remote_path/"
  # shellcheck disable=SC2029  # intentional client-side expansion of $remote_path
  if ! ssh -o ConnectTimeout=15 -o BatchMode=yes "$BIGBLACK_SSH" "mkdir -p '$remote_path'"; then
    echo "✗ SSH to $BIGBLACK_SSH failed — site not published." >&2
    echo "  Common causes:" >&2
    echo "    • Tailscale not running   (this script publishes via MagicDNS)" >&2
    echo "    • SSH keys not loaded     (BatchMode=yes prevents interactive auth)" >&2
    echo "    • bigblack offline" >&2
    echo "  Quick diagnose:  ssh $BIGBLACK_SSH echo ok" >&2
    echo "  See references/publishing.md for the bigblack/Tailscale setup." >&2
    return 1
  fi
  if ! rsync -av --delete \
        --timeout=30 \
        -e "ssh -o ConnectTimeout=15 -o BatchMode=yes" \
        --exclude '.git/' \
        --exclude '.DS_Store' \
        --exclude '*.swp' \
        --exclude 'node_modules/' \
        --exclude '__pycache__/' \
        --exclude '.venv/' \
        --exclude '.published.json.tmp.*' \
        "$local_dir/" "$BIGBLACK_SSH:$remote_path/"; then
    echo "✗ rsync failed — site may be partially updated. Re-run scripts/site.sh push <site> to retry." >&2
    return 1
  fi

  # 4. Stamp provenance only AFTER rsync confirmed success. Atomic via
  # tmp + mv so a SIGINT during this step doesn't leave an unparseable
  # `.published.json`. Write to local; rsync's already done — the
  # next push (or a fresh re-run) will mirror this stamp to bigblack.
  local tmpfile
  tmpfile=$(mktemp "$local_dir/.published.json.tmp.XXXXXX")
  cat > "$tmpfile" <<JSON
{
  "project": "$project",
  "page": "$page",
  "commit": "${commit_sha}${dirty}",
  "published_utc": "$timestamp",
  "source_repo": "$source_repo",
  "url": "$url"
}
JSON
  mv -f "$tmpfile" "$local_dir/.published.json"

  echo ""
  echo "✓ published"
  echo "  URL:    $url"
  echo "  Path:   $BIGBLACK_SSH:$remote_path"
  echo "  Commit: ${commit_sha}${dirty}"
}

cmd_url() {
  local local_dir="${1:?url <local-dir>}"
  [[ -d "$local_dir" ]] || { echo "not a directory: $local_dir" >&2; exit 1; }
  build_url "$local_dir"
}

cmd_list() {
  echo "=== $SERVER_BASE_URL ==="
  # Single SSH call: print "<project>/<page>" for each two-level entry under sites root.
  # Process substitution avoids SC2095 (ssh swallowing stdin in pipeline).
  local last_project=""
  # shellcheck disable=SC2029  # intentional client-side expansion of $BIGBLACK_ROOT
  while IFS=/ read -r proj page; do
    [[ -z "$proj" ]] && continue
    if [[ "$proj" != "$last_project" ]]; then
      echo ""
      echo "  /$proj/"
      last_project="$proj"
    fi
    [[ -n "$page" ]] && echo "    /$page"
  done < <(ssh "$BIGBLACK_SSH" "find '$BIGBLACK_ROOT' -mindepth 1 -maxdepth 2 -type d -printf '%P\n' 2>/dev/null | sort")
}

cmd_unpublish() {
  local local_dir="${1:?unpublish <local-dir>}"
  [[ -d "$local_dir" ]] || { echo "not a directory: $local_dir" >&2; exit 1; }
  local remote_path url
  remote_path="$(build_remote_path "$local_dir")"
  url="$(build_url "$local_dir")"
  echo "About to remove: $BIGBLACK_SSH:$remote_path"
  echo "URL that will 404: $url"
  read -r -p "Confirm unpublish? (yes/NO) " ans
  [[ "$ans" == "yes" ]] || { echo "aborted"; exit 0; }
  # shellcheck disable=SC2029  # intentional client-side expansion of $remote_path
  ssh "$BIGBLACK_SSH" "rm -rf '$remote_path'"
  echo "✓ unpublished"
}

case "${1:-}" in
  nav)       shift; cmd_nav       "$@" ;;
  search)    shift; cmd_search    "$@" ;;
  push)      shift; cmd_push      "$@" ;;
  check)     shift; cmd_check     "$@" ;;
  url)       shift; cmd_url       "$@" ;;
  list)              cmd_list ;;
  unpublish) shift; cmd_unpublish "$@" ;;
  *)
    cat <<EOF
Usage: $0 <command> [args]

Commands:
  nav <local-dir>         Regenerate site-map + auto-nav + search index
  search <local-dir>      Rebuild Pagefind search index only
  push <local-dir>        Build nav + validate + rsync to bigblack
  check <local-dir>       Build nav + validate (lychee + orphan-page check)
  url <local-dir>         Print the URL where <local-dir> publishes to
  list                    List all published pages on bigblack
  unpublish <local-dir>   Remove the page from bigblack

Environment overrides:
  SITE_PROJECT_NAME       Project namespace (default: from git remote, or
                          basename of the working tree when not in a git repo)
  SITE_BIGBLACK_SSH       SSH alias (default: bigblack)
  SITE_BIGBLACK_ROOT      Remote root (default: /home/tca/sites)
  SITE_BASE_URL           Public URL (default: https://bigblack.tail0f299b.ts.net:8448)
  CLAUDE_PLUGIN_ROOT      Plugin install path (set automatically by Claude
                          Code when this script is invoked via the skill;
                          used as a fallback when scripts/build-nav.py is
                          not present in the consuming repo)
  PAGEFIND_BIN            Override path to the pagefind binary (default:
                          ~/.local/bin/pagefind, falling back to PATH)
EOF
    exit 1 ;;
esac

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ PAGE TITLE }} — {{ SUBJECT }}</title>
  <meta name="description" content="{{ ONE-LINE DESCRIPTION }}">

  <!--
    Two-hierarchy stylesheet pattern:
      H1 (kernel)    — canonical design system, served from jsDelivr CDN
      H2 (overrides) — optional per-page tweaks (colors, density). Tiny file.
    Order matters: kernel first, overrides last so cascade lets you win.
  -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/terrylica/cc-skills@main/plugins/html-showcase/assets/showcase.css">
  <link rel="stylesheet" href="overrides.css">
  <!--
    The auto-nav rail's <link> and <script> are injected here by
    scripts/build-nav.py — do not hand-edit the lines marked id="auto-nav-css"
    and id="auto-nav-js"; they're rewritten on every nav build.
  -->
</head>
<body>

  <!--
    Sitemap-driven navigation rail.

    The rail HTML between AUTO-NAV-START and AUTO-NAV-END is generated
    by scripts/build-nav.py; do not hand-edit. Re-running the script
    after adding/renaming pages refreshes every page's rail in place.
    If these markers are missing, build-nav.py inserts them right after
    <body>.
  -->
  <!-- AUTO-NAV-START -->
  <!-- AUTO-NAV-END -->

  <!-- ============================================================== -->
  <!-- 1. HERO                                                          -->
  <!-- ============================================================== -->
  <header class="hero">
    <div class="shell hero__inner">
      <div class="hero__eyebrow">
        <span class="hero__pulse" aria-hidden="true"></span>
        <span>{{ EYEBROW LABEL · MAX ~70 chars }}</span>
      </div>
      <h1 class="hero__title">{{ ONE-LINE HEADLINE }}</h1>
      <p class="hero__lede">
        {{ 2–3 SENTENCE LEDE THAT SUMMARIZES WHAT THIS PAGE PRESENTS.
           Mention the most concrete metric or finding up front. }}
      </p>
      <div class="hero__cta-row">
        <a class="chip chip--solid" href="#section-anchor">{{ PRIMARY CTA }}</a>
        <a class="chip chip--ghost" href="#another-anchor">{{ SECONDARY }}</a>
        <a class="chip chip--ghost" href="https://example.com" rel="noopener">{{ EXTERNAL ↗ }}</a>
      </div>
    </div>
  </header>

  <main class="shell">

    <!-- ========================================================== -->
    <!-- 2. AT-A-GLANCE METRICS — 3 to 5 cards in a responsive grid  -->
    <!-- ========================================================== -->
    <section class="section" id="at-a-glance" aria-labelledby="metrics-h">
      <div class="section-head">
        <h2 id="metrics-h">{{ SECTION TITLE }}</h2>
        <span class="section-head__hint">{{ DATE RANGE OR PROVENANCE }}</span>
      </div>

      <div class="metric-grid">
        <article class="metric-card">
          <p class="metric-card__label">{{ LABEL }}</p>
          <p class="metric-card__value">{{ NUMBER }}</p>
          <p class="metric-card__hint">{{ ONE-LINE CONTEXT }}</p>
        </article>
        <article class="metric-card metric-card--accent">
          <p class="metric-card__label">{{ LABEL }}</p>
          <p class="metric-card__value">{{ NUMBER }}</p>
          <p class="metric-card__hint">{{ ONE-LINE CONTEXT }}</p>
        </article>
        <article class="metric-card metric-card--success">
          <p class="metric-card__label">{{ LABEL }}</p>
          <p class="metric-card__value">{{ NUMBER }}</p>
          <p class="metric-card__hint">{{ ONE-LINE CONTEXT }}</p>
        </article>
        <article class="metric-card metric-card--warning">
          <p class="metric-card__label">{{ LABEL }}</p>
          <p class="metric-card__value">{{ NUMBER }}</p>
          <p class="metric-card__hint">{{ ONE-LINE CONTEXT }}</p>
        </article>
      </div>
    </section>

    <!-- ========================================================== -->
    <!-- 3. ITEM QUEUE — many small cards (bugs, items, links, etc.) -->
    <!-- ========================================================== -->
    <section class="section" id="queue" aria-labelledby="queue-h">
      <div class="section-head">
        <h2 id="queue-h">{{ SECTION TITLE }}</h2>
        <span class="section-head__hint">{{ COUNT OR PROVENANCE }}</span>
      </div>
      <p class="section-intro">{{ ONE-PARAGRAPH FRAMING (optional, can omit). }}</p>

      <div class="bug-grid">
        <article class="bug-card bug-card--high">
          <div class="bug-card__head">
            <a class="bug-card__id" href="https://example.com/123" rel="noopener">#123</a>
            <span class="badge badge--high">High</span>
          </div>
          <p class="bug-card__title">{{ ONE-LINE ROOT CAUSE OR STATUS }}</p>
        </article>
        <article class="bug-card">
          <div class="bug-card__head">
            <a class="bug-card__id" href="https://example.com/124" rel="noopener">#124</a>
            <span class="badge badge--medium">Medium</span>
          </div>
          <p class="bug-card__title">{{ ONE-LINE ROOT CAUSE OR STATUS }}</p>
        </article>
        <article class="bug-card">
          <div class="bug-card__head">
            <a class="bug-card__id" href="https://example.com/125" rel="noopener">#125</a>
            <span class="badge badge--info">Info</span>
          </div>
          <p class="bug-card__title">{{ ONE-LINE ROOT CAUSE OR STATUS }}</p>
        </article>
      </div>
    </section>

  </main>

  <!-- ============================================================== -->
  <!-- FOOTER · PROVENANCE — every claim should link to its source     -->
  <!-- ============================================================== -->
  <footer class="site-footer">
    <div class="shell">
      <h2 class="visually-hidden">Provenance</h2>
      <div class="site-footer__grid">
        <div>
          <h3>{{ GROUP A }}</h3>
          <ul>
            <li><a href="https://example.com/source-1" rel="noopener">{{ SOURCE 1 }}</a></li>
            <li><a href="https://example.com/source-2" rel="noopener">{{ SOURCE 2 }}</a></li>
          </ul>
        </div>
        <div>
          <h3>{{ GROUP B }}</h3>
          <ul>
            <li><a href="https://example.com/source-3" rel="noopener">{{ SOURCE 3 }}</a></li>
          </ul>
        </div>
      </div>
      <div class="site-footer__legal">
        <span>All claims verifiable via the linked artifacts. Lychee-checked, orphan-page-validated.</span>
        <span>v1 · {{ YYYY-MM-DD }}</span>
      </div>
    </div>
  </footer>

</body>
</html>

# Lychee link-checker config for the contractor showcase mini-site.
# Run via:  mise run site:check
# Docs:     https://lychee.cli.rs/

# Only follow http(s) and same-directory relative links
include = ["^https?://", "^/", "^\\."]

# Skip schemes / private hosts that lychee can't validate
exclude = [
  "^mailto:",
  "^tel:",
  "127\\.0\\.0\\.1",
  "localhost",
  "0\\.0\\.0\\.0",
]

# Network behaviour
max_redirects = 5
timeout = 15
max_concurrency = 4
retry_wait_time = 2
accept = [200, 206, 301, 302, 304]

# GitHub rate-limit etiquette: cache 7d so re-runs are fast and rarely 429
cache = true
max_cache_age = "7d"

# Verbose output for the human; CI can switch via --format json
verbose = "info"
no_progress = false

/* =============================================================================
 * overrides.css — per-page customization on top of the canonical kernel.
 *
 * Copy this file to `overrides.css` next to your `index.html`. It must be
 * linked AFTER showcase.css so the cascade lets your overrides win.
 *
 * The kernel exposes ~30 CSS custom properties; the most useful ones are
 * shown below. Set only the ones you need; leave everything else inheriting
 * from the kernel.
 *
 * To find the full list of overridable tokens, view the kernel:
 *   https://cdn.jsdelivr.net/gh/terrylica/cc-skills@main/plugins/html-showcase/assets/showcase.css
 *
 * Search inside it for `:root {` — every variable defined there is overridable.
 * ============================================================================= */

:root {
  /* === DENSITY KNOBS — universal layout multipliers ====================== */
  /* --density: 1.00; */    /* baseline; lower = tighter, higher = airier */
  /* --font-scale: 1.00; */ /* base font size multiplier */

  /* === BRAND ============================================================ */
  /* --brand-primary: #2563eb; */
  /* --brand-primary-strong: #1d4ed8; */
  /* --brand-primary-deep: #1e3a8a; */
  /* --brand-accent: #7c3aed; */
  /* --brand-accent-deep: #4c1d95; */
  /* --brand-amber: #f59e0b; */
  /* --brand-emerald: #10b981; */

  /* === SURFACE / TEXT (rarely needs overriding) ========================= */
  /* --surface-page: #0b1120; */
  /* --surface-card: #111c33; */
  /* --text-headline: #e2e8f0; */
  /* --text-body: #cbd5e1; */
  /* --text-muted: #94a3b8; */

  /* === FONTS ============================================================ */
  /* --font-display: "Inter Tight", "Inter", system-ui, sans-serif; */
  /* --font-text: "Inter", system-ui, sans-serif; */
  /* --font-mono-stack: "JetBrains Mono", ui-monospace, monospace; */

  /* === LAYOUT WIDTH ===================================================== */
  /* --shell-max: 1200px; */
}

/* You may also add page-specific component classes here — but resist the urge.
 * If a pattern repeats across pages, it belongs in the kernel CSS instead.
 */

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ SECTION TITLE }} — {{ SITE NAME }}</title>
  <meta name="description" content="{{ ONE-LINE DESCRIPTION OF THIS SECTION }}">

  <!--
    Section landing page — sits at <site-root>/<section-slug>/index.html.
    Sibling pages live next to this file as *.html. Sections sort
    newest-first when slugs match YYYY-MM-DD-<rest>; otherwise A-Z.
  -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/terrylica/cc-skills@main/plugins/html-showcase/assets/showcase.css">
  <link rel="stylesheet" href="../overrides.css">
  <!-- auto-nav.css/js are injected here by scripts/build-nav.py -->
</head>
<body>

  <!-- AUTO-NAV-START -->
  <!-- AUTO-NAV-END -->

  <header class="hero">
    <div class="shell hero__inner">
      <div class="hero__eyebrow">
        <span class="hero__pulse" aria-hidden="true"></span>
        <span>Section · {{ DATE OR LABEL }}</span>
      </div>
      <h1 class="hero__title">{{ SECTION HEADLINE }}</h1>
      <p class="hero__lede">
        {{ 1–2 SENTENCES THAT FRAME WHAT THIS SECTION COVERS AND WHY IT EXISTS. }}
      </p>
    </div>
  </header>

  <main class="shell">

    <!--
      Section index = a list of sibling pages. Keep it semantic; the
      auto-nav rail also lists them, but the body links here let the
      page stand alone (e.g. when shared as a single URL with no rail).
    -->
    <section class="section">
      <div class="section-head">
        <h2>Pages in this section</h2>
        <span class="section-head__hint">{{ COUNT }} pages</span>
      </div>

      <ul class="rail-list">
        <li><a class="rail-link" href="{{ PAGE-1.html }}">📄 {{ PAGE 1 TITLE }}</a></li>
        <li><a class="rail-link" href="{{ PAGE-2.html }}">📄 {{ PAGE 2 TITLE }}</a></li>
      </ul>
    </section>

  </main>

  <footer class="site-footer">
    <div class="shell">
      <div class="site-footer__legal">
        <span>Section index · auto-discovered by <code>scripts/build-nav.py</code></span>
        <span>{{ YYYY-MM-DD }}</span>
      </div>
    </div>
  </footer>

</body>
</html>