211 lines
8.0 KiB
Bash
Executable File
211 lines
8.0 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
|
|
result = subprocess.run(
|
|
["find", str(skills_dir), "-name", "SKILL.md", "-type", "f"],
|
|
capture_output=True, text=True
|
|
)
|
|
skill_files = [Path(p) for p in result.stdout.strip().split('\n') if p]
|
|
|
|
# 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/`.",
|
|
"",
|
|
"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" |