Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.5 KB
Raw Blame
#!/usr/bin/env bash
# scripts/check-bootstrap-tag.sh — sanctioned-distribution-ref guard [C1 = D6-A].
#
# The agent-bootstrap distribution contract (docs/designs/AGENT_BOOTSTRAP_PLAN.md,
# "Release mechanics") is a SINGLE maintainer-controlled ref: `stable`, moved by
# .github/workflows/promote-stable.yml only to a published release whose exact
# tree passed the production soak (docs/RELEASING.md#stable-channel-promotion).
# The latest-stable ref (every release, the alpha line) is refused here: new users
# start on stable. Paste blocks copied into the wild never
# rot and never point at an unreviewed branch head. This guard keeps the two
# public entry documents on that contract:
#
#   1. Every raw.githubusercontent.com/garrytan/gbrain/<ref>/<path> reference
#      in README.md and BOOTSTRAP_FOR_AGENTS.md uses <ref> = stable.
#      Carve-out: <path> = INSTALL_FOR_AGENTS.md — that is the pre-bootstrap
#      OpenClaw/Hermes headline install path with its own (master) contract,
#      outside the bootstrap ref rule.
#   2. Every explicit `github:garrytan/gbrain#<ref>` install pin in those
#      files is #stable — no v-prefixed pins, no branch refs
#      (master/main). The historical un-pinned `github:garrytan/gbrain`
#      quick-start form is tolerated (it predates bootstrap and is owned by
#      the README task).
#   3. BOOTSTRAP_FOR_AGENTS.md embeds `<!-- gbrain-runbook-stamp: X.Y.Z.W -->`
#      equal to the VERSION file — `bootstrap status` compares that stamp to
#      the installed binary (supply-chain skew check).
#
# SKIP-GRACEFUL: files that don't exist yet are skipped with a SKIP message
# (exit 0) so CI stays green until the bootstrap doors task lands.
#
# Modeled on scripts/check-key-files-current-state.sh. BSD/GNU grep portable
# (no \t escapes, no GNU-only flags).
#
# Env overrides (for this guard's own test):
#   GBRAIN_BOOTSTRAP_GUARD_ROOT   repo root to scan (default: script's ../)
#
# Exit codes:
#   0   clean (or everything skipped)
#   1   violation

set -uo pipefail

ROOT="${GBRAIN_BOOTSTRAP_GUARD_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
SANCTIONED=$(sed -n "s/^export const INSTALL_REF = '\(.*\)';$/\1/p" "$(cd "$(dirname "$0")/.." && pwd)/src/core/install-ref.ts")
[ -n "$SANCTIONED" ] || { echo 'FAIL: could not read INSTALL_REF from src/core/install-ref.ts' >&2; exit 1; }

# URL terminators: whitespace, ), <, >, ", ', backtick. Built by concatenation
# so the single quote and backtick stay literal.
RAW_URL_RE='raw\.githubusercontent\.com/garrytan/gbrain/[^/[:space:]]+/[^[:space:])<>"'\''`]*'
PIN_RE='github:garrytan/gbrain#[0-9A-Za-z._/-]+'

fail=0
checked=0

for rel in README.md BOOTSTRAP_FOR_AGENTS.md; do
  f="$ROOT/$rel"
  if [ ! -f "$f" ]; then
    echo "SKIP: $rel absent — nothing to check yet"
    continue
  fi
  checked=$((checked + 1))

  # ── Rule 1: raw fetch refs must pin the sanctioned ref ────────────────────
  raw_refs=$(grep -oE "$RAW_URL_RE" "$f" | LC_ALL=C sort -u || true)
  while IFS= read -r u; do
    [ -n "$u" ] || continue
    rest="${u#raw.githubusercontent.com/garrytan/gbrain/}"
    ref="${rest%%/*}"
    path="${rest#*/}"
    [ "$ref" = "$SANCTIONED" ] && continue
    [ "$path" = "INSTALL_FOR_AGENTS.md" ] && continue
    fail=1
    echo "FAIL: $rel references unsanctioned ref '$ref': $u" >&2
    echo "      Bootstrap fetch URLs must use the maintainer-controlled '$SANCTIONED' ref" >&2
    echo "      (no v-prefixed pins, no branch refs). See .github/workflows/release.yml." >&2
  done <<< "$raw_refs"

  # ── Rule 2: explicit install pins must be #stable ────────────────────────
  pins=$(grep -oE "$PIN_RE" "$f" | LC_ALL=C sort -u || true)
  while IFS= read -r p; do
    [ -n "$p" ] || continue
    ref="${p#github:garrytan/gbrain#}"
    if [ "$ref" != "$SANCTIONED" ]; then
      fail=1
      echo "FAIL: $rel pins the install to '#$ref' ($p)." >&2
      echo "      The only sanctioned install pin is github:garrytan/gbrain#$SANCTIONED." >&2
    fi
  done <<< "$pins"
done

# ── Rule 3: runbook stamp equals VERSION ────────────────────────────────────
runbook="$ROOT/BOOTSTRAP_FOR_AGENTS.md"
if [ -f "$runbook" ]; then
  version_file="$ROOT/VERSION"
  if [ ! -f "$version_file" ]; then
    echo "SKIP: VERSION file absent — cannot check the runbook stamp"
  else
    version="$(tr -d '[:space:]' < "$version_file")"
    stamp="$(grep -oE '<!-- gbrain-runbook-stamp: [0-9A-Za-z.-]+ -->' "$runbook" \
      | head -1 \
      | sed -E 's/<!-- gbrain-runbook-stamp: (.+) -->/\1/')"
    if [ -z "$stamp" ]; then
      fail=1
      echo "FAIL: BOOTSTRAP_FOR_AGENTS.md is missing its '<!-- gbrain-runbook-stamp: X.Y.Z.W -->' line." >&2
      echo "      bootstrap status compares this stamp to the installed binary (skew check)." >&2
    elif [ "$stamp" != "$version" ]; then
      fail=1
      echo "FAIL: BOOTSTRAP_FOR_AGENTS.md stamp '$stamp' != VERSION '$version'." >&2
      echo "      Refresh the runbook stamp in the same commit as the VERSION bump." >&2
    fi
  fi
fi

# ── Rule 4: plugin marketplace refs pin a sanctioned ref ─────────────────────
# `codex plugin marketplace add garrytan/gbrain@<ref>` in docs must use the
# stable channel (@stable) or the slim dist branch (@codex-plugin).
# The @-less form (`plugin marketplace add garrytan/gbrain`) is deliberately
# OUT of scope: Claude Code marketplace adds have no ref pin syntax, so the
# Claude lane documents the bare form and installs the repo default branch —
# a recorded decision, not a gate hole. Codex docs headline the pinned form.
while IFS=: read -r file line match; do
  ref="${match##*@}"
  case "$ref" in
    "$SANCTIONED"|codex-plugin) ;;
    *)
      fail=1
      echo "FAIL: $file:$line pins 'marketplace add garrytan/gbrain@$ref' — use @$SANCTIONED or @codex-plugin." >&2
      ;;
  esac
done < <(grep -RInE 'plugin marketplace add garrytan/gbrain@[A-Za-z0-9._-]+' \
  "$ROOT/README.md" "$ROOT/BOOTSTRAP_FOR_AGENTS.md" "$ROOT/INSTALL_FOR_AGENTS.md" "$ROOT/docs" 2>/dev/null \
  | sed -E 's/^([^:]+):([0-9]+):.*(plugin marketplace add garrytan\/gbrain@[A-Za-z0-9._-]+).*/\1:\2:\3/' || true)

if [ "$fail" -ne 0 ]; then
  exit 1
fi
if [ "$checked" -eq 0 ]; then
  echo "check-bootstrap-tag: ok (no bootstrap entry docs present yet — all checks skipped)"
  echo "GBRAIN_CHECK_SKIPPED: no bootstrap entry docs present"
else
  echo "check-bootstrap-tag: ok ($checked doc(s) on the '$SANCTIONED' distribution ref)"
fi