Files
agent-estate-wiki/wiki-maintain.sh
T

222 lines
8.7 KiB
Bash
Executable File

#!/usr/bin/env bash
# wiki-maintain.sh — Agent Estate Wiki maintenance entrypoint
# Run daily at 03:00 AWST via cron (wiki-stocktake-maintenance job)
#
# Does three things:
# 1. Regenerates systems/skills-index.md from live ~/.hermes/skills/ tree
# 2. Audits EVERY page for staleness (>21 days since `updated` frontmatter)
# 3. Rebuilds Quartz static site into public/
set -euo pipefail
WIKI_DIR="/home/hermes/workspace/agent-estate-wiki"
SKILLS_DIR="$HOME/.hermes/skills"
STOCKTAKE_DIR="$WIKI_DIR/raw/stocktake"
QUARTZ_CONTENT_DIR="$WIKI_DIR/public"
TODAY=$(date +%Y%m%d)
cd "$WIKI_DIR"
echo "[wiki-maintain] Starting maintenance at $(date -Iseconds)"
echo ""
# =============================================================================
# [1/3] Regenerate skills-index.md from live skill tree
# =============================================================================
echo "[1/3] Regenerating systems/skills-index.md from $SKILLS_DIR..."
python3 << 'PYTHON_SCRIPT'
import sys
from pathlib import Path
from datetime import date
import subprocess
skills_dir = Path("/home/hermes/.hermes/skills")
output = Path("/home/hermes/workspace/agent-estate-wiki/systems/skills-index.md")
# Use find to get all SKILL.md files, then group by their immediate parent category
# This handles nested structures like context-engineering-collection/skills/foo/SKILL.md
# Archived skills (`.archive/`) are parked, not installed — the loader does not
# expose them, so they are excluded from the count (see
# incidents/2026-08-15-skills-index-drift.md).
def _find(*extra):
r = subprocess.run(
["find", str(skills_dir), *extra], capture_output=True, text=True
)
return [Path(p) for p in r.stdout.strip().split('\n') if p]
skill_files = _find("-name", "SKILL.md", "-type", "f", "-not", "-path", "*/.archive/*")
archived_files = _find("-path", "*/.archive/*", "-name", "SKILL.md", "-type", "f")
# Group by the top-level category (first directory under skills_dir)
categories = {}
for skill_md in skill_files:
# Get relative path from skills_dir
try:
rel = skill_md.relative_to(skills_dir)
except ValueError:
continue # Skip if not under skills_dir (e.g., broken symlinks)
# Top-level category is the first part of the path
category = rel.parts[0]
skill_name = skill_md.parent.name # The directory containing SKILL.md
# Read the description from the skill file
try:
content = skill_md.read_text(errors='ignore')[:2000]
lines = content.split('\n')
desc = ""
in_frontmatter = False
for line in lines:
if line.strip() == '---':
in_frontmatter = not in_frontmatter
continue
if not in_frontmatter and line.strip():
desc = line.strip()
break
if len(desc) > 200:
desc = desc[:197] + "..."
except Exception as e:
desc = f"[error reading: {e}]"
if category not in categories:
categories[category] = []
# Avoid duplicates (same skill_name in same category)
if not any(name == skill_name for name, _ in categories[category]):
categories[category].append((skill_name, desc))
# Sort skills within each category
for cat in categories:
categories[cat] = sorted(categories[cat], key=lambda x: x[0])
# Build the markdown
today = date.today().isoformat()
lines = [
"---",
"title: Installed Skills",
"type: system",
"status: active",
"created: 2026-07-22",
f"updated: {today}",
f"verified_on: {today}",
"confidence: high",
"tags: [skills, hermes]",
"sources: []",
"---",
"",
"# Installed Skills",
"",
f"**Total installed: {sum(len(v) for v in categories.values())} skills** in `~/.hermes/skills/`.",
"",
f"- **{len(archived_files)} archived skills** are parked under `~/.hermes/skills/.archive/` and are "
"excluded from this count — the loader does not expose them.",
"- The loader's own catalogue (`hermes skills list`, e.g. *34 hub-installed, 52 builtin, N local — "
"N enabled*) is the authoritative loadable figure; this page is a filesystem inventory.",
"",
"This page is auto-regenerated from the live skill inventory. Do not hand-edit.",
"",
"## Stock-take notes",
"- Category = directory structure under `~/.hermes/skills/` (`category/skill/SKILL.md`).",
"- Skills directly under `~/.hermes/skills/` group under `uncategorized`.",
"",
]
# Write categories (sorted, excluding 'uncategorized' which goes last)
for cat_name in sorted(categories.keys()):
skills = categories[cat_name]
# Format category name (capitalize first letter of each word)
cat_display = cat_name.replace('-', ' ').title()
lines.append(f"## {cat_display} ({len(skills)})")
lines.append("")
for skill_name, desc in skills:
# Format skill name
skill_display = skill_name.replace('-', ' ')
if desc:
lines.append(f"- `{skill_name}` — {desc}")
else:
lines.append(f"- `{skill_name}` — (no description)")
lines.append("")
output.write_text('\n'.join(lines))
print(f" Written {output} with {sum(len(v) for v in categories.values())} skills in {len(categories)} categories")
PYTHON_SCRIPT
echo ""
# =============================================================================
# [2/3] Freshness audit — check every page's `updated` frontmatter
# =============================================================================
REPORT="$STOCKTAKE_DIR/freshness-$TODAY.txt"
echo "[2/3] Auditing wiki freshness (threshold: >21 days)..."
python3 "$STOCKTAKE_DIR/_freshness_audit.py" "$WIKI_DIR" "$REPORT" 21
echo ""
# =============================================================================
# [3/3] Rebuild Quartz static site and deploy to public/
# =============================================================================
# Quartz v4/v5 lives in a SEPARATE source tree (/home/hermes/workspace/quartz-temp);
# the wiki repo only holds the Markdown. The build reads content/ from that tree
# and emits public/ there, which we then deploy into the wiki repo's public/.
#
# PITFALL (hit 2026-10-20): the previous version of this step tested for
# `quartz.config.ts` and `npx`, and the repo has NEITHER — Quartz v4/v5 uses
# `quartz.config.yaml`. The test always failed, so the site silently stopped
# being rebuilt (published site was 40 days stale). Do not reintroduce a
# config-file existence test that isn't the real one: check quartz.config.yaml.
echo "[3/3] Rebuilding Quartz static site..."
QUARTZ_DIR="/home/hermes/workspace/quartz-temp"
QUARTZ_CONTENT="$QUARTZ_DIR/content"
QUARTZ_PUBLIC="$QUARTZ_DIR/public"
QUARTZ_DEPLOY_DIR="$WIKI_DIR/public"
if [ ! -f "$QUARTZ_DIR/quartz.config.yaml" ]; then
echo " ERROR: $QUARTZ_DIR/quartz.config.yaml not found — cannot build the Quartz site." >&2
echo " The published site will stay stale. Fix the Quartz source tree before continuing." >&2
exit 1
fi
# --- sync wiki Markdown into the Quartz content tree -------------------------
# raw/ is excluded on purpose: it holds raw config dumps and the stocktake
# reports, which have never been part of the published site. public/ and .git
# are excluded to avoid copying build output into the input tree.
rm -rf "$QUARTZ_CONTENT"
mkdir -p "$QUARTZ_CONTENT"
tar -C "$WIKI_DIR" \
--exclude=./public --exclude=./.git --exclude=./node_modules --exclude=./raw \
-cf - . | tar -C "$QUARTZ_CONTENT" -xf -
echo " Synced wiki content into $QUARTZ_CONTENT"
# --- build -------------------------------------------------------------------
cd "$QUARTZ_DIR"
# PIPESTATUS is required: a plain pipeline would report tail's exit code (0)
# and silently swallow a failed build.
npx quartz build 2>&1 | tail -8
BUILD_RC=${PIPESTATUS[0]}
if [ "$BUILD_RC" -ne 0 ]; then
echo " ERROR: Quartz build failed (exit $BUILD_RC)." >&2
exit 1
fi
# --- deploy ------------------------------------------------------------------
# Clear the CONTENTS of public/ rather than removing the directory itself:
# hermes-wiki-serve.service runs with its cwd inside public/, so replacing the
# directory inode leaves the running server serving a deleted directory (all
# requests 404) until it is restarted.
find "$QUARTZ_DEPLOY_DIR" -mindepth 1 -delete
cp -a "$QUARTZ_PUBLIC/." "$QUARTZ_DEPLOY_DIR/"
echo " Deployed $(find "$QUARTZ_DEPLOY_DIR" -type f | wc -l) files to $QUARTZ_DEPLOY_DIR"
systemctl --user restart hermes-wiki-serve.service 2>/dev/null \
&& echo " Restarted hermes-wiki-serve.service" \
|| echo " WARNING: could not restart hermes-wiki-serve.service — verify the site manually"
echo ""
echo "[wiki-maintain] Maintenance complete at $(date -Iseconds)"
echo " Freshness report: $REPORT"
echo ""
# Print summary
head -5 "$REPORT"
tail -3 "$REPORT"