Add docs/wiki source tree and Gitea Wiki sync helper (#224)

Bootstrap repo-tracked wiki pages (10 required pages), the operator- confirmed sync script, PR template publication gate, and safety tests so Gitea-Tools can publish to the live Gitea Wiki per issue #224. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-07-06 01:36:10 -04:00
parent 125f52a059
commit f58317d079
13 changed files with 507 additions and 0 deletions
@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# sync-gitea-wiki.sh — mirror the repo-tracked docs/wiki/ pages into the
+# Gitea native wiki. docs/wiki/ remains the source of truth; the Gitea Wiki
+# is a read convenience mirrored FROM it, never edited directly.
+#
+#   scripts/sync-gitea-wiki.sh            dry-run (default): print the plan
+#   scripts/sync-gitea-wiki.sh --push     actually sync, ONLY with the exact
+#                                         confirmation below
+#
+# Safety contract:
+# - Dry-run is the default and performs no network or repository-mutating
+#   operation (only a local read of the origin remote URL).
+# - A push requires GITEA_WIKI_SYNC_CONFIRM to equal exactly
+#   "SYNC WIKI <repo-name>" (repo name derived from the origin remote).
+#   Anything else refuses before any clone happens.
+# - The wiki remote is derived from the local origin remote; nothing is
+#   hardcoded here and no credential material is read, printed, or stored
+#   by this script — git's own configured auth is used as-is.
+# - Only *.md pages from docs/wiki/ are mirrored; nothing else is touched
+#   and no page is deleted from the wiki by this script.
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "$here/.." && pwd)"
+wiki_src="$repo_root/docs/wiki"
+
+[ -d "$wiki_src" ] || { echo "error: $wiki_src not found" >&2; exit 1; }
+
+if git -C "$repo_root" remote get-url origin >/dev/null 2>&1; then
+  origin_url="$(git -C "$repo_root" remote get-url origin)"
+elif git -C "$repo_root" remote get-url prgs >/dev/null 2>&1; then
+  origin_url="$(git -C "$repo_root" remote get-url prgs)"
+else
+  echo "error: configure an origin or prgs git remote" >&2
+  exit 1
+fi
+repo_name="$(basename "$origin_url" .git)"
+wiki_remote="${origin_url%.git}.wiki.git"
+expected_confirm="SYNC WIKI $repo_name"
+
+pages=()
+while IFS= read -r -d '' f; do
+  pages+=("$(basename "$f")")
+done < <(find "$wiki_src" -maxdepth 1 -name '*.md' -print0 | sort -z)
+
+mode="${1:-}"
+
+if [ "$mode" != "--push" ]; then
+  echo "dry-run: would sync ${#pages[@]} pages from docs/wiki/ to the '$repo_name' Gitea Wiki:"
+  for p in "${pages[@]}"; do
+    echo "  $p"
+  done
+  echo "dry-run: no git or network operation performed."
+  echo "To sync for real: GITEA_WIKI_SYNC_CONFIRM=\"$expected_confirm\" $0 --push"
+  exit 0
+fi
+
+if [ "${GITEA_WIKI_SYNC_CONFIRM:-}" != "$expected_confirm" ]; then
+  echo "refused: --push requires GITEA_WIKI_SYNC_CONFIRM to equal exactly:" >&2
+  echo "  $expected_confirm" >&2
+  exit 1
+fi
+
+workdir="$(mktemp -d)"
+trap 'rm -rf "$workdir"' EXIT
+
+echo "cloning wiki repository for '$repo_name'"
+if ! git clone --quiet -- "$wiki_remote" "$workdir/wiki" 2>/dev/null; then
+  echo "error: could not clone the wiki repository. If this repo's wiki has" >&2
+  echo "never been initialized, create its first page once in the Gitea UI" >&2
+  echo "(Wiki tab -> New Page), then re-run this script." >&2
+  exit 1
+fi
+
+cp "$wiki_src"/*.md "$workdir/wiki/"
+
+if git -C "$workdir/wiki" status --porcelain | grep -q .; then
+  git -C "$workdir/wiki" add -A
+  git -C "$workdir/wiki" commit --quiet -m "docs: sync from repo docs/wiki (source of truth)"
+  echo "pushing wiki update for '$repo_name'"
+  git -C "$workdir/wiki" push --quiet
+  echo "done: ${#pages[@]} pages synced."
+else
+  echo "done: wiki already up to date; nothing pushed."
+fi