From a960b1809a7f4a186a1974096a782076625b0d11 Mon Sep 17 00:00:00 2001
From: virgil <virgil.prime@proton.me>
Date: Mon, 8 Jun 2026 11:31:05 -0700
Subject: [PATCH] Add Section 0 helper trace events

---
 scripts/setup-section0-docs.sh | 68 ++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/scripts/setup-section0-docs.sh b/scripts/setup-section0-docs.sh
index bae9479..f8a0c8d 100755
--- a/scripts/setup-section0-docs.sh
+++ b/scripts/setup-section0-docs.sh
@@ -41,6 +41,7 @@ REPO_DIR="$TARGET_DIR"
 SERVER_URL="$SERVER_URL"
 SESSION_DIR="\${SECTION0_SESSION_DIR:-\$HOME/.config/section0-docs}"
 SESSION_PATH="\$SESSION_DIR/session.json"
+EVENTS_PATH="\$SESSION_DIR/events.jsonl"
 
 usage() {
   cat <<USAGE
@@ -58,6 +59,7 @@ Commands:
   commit    commit all current changes with MESSAGE
   push      push current branch
   push-test prove write access with a temporary remote branch
+  trace     show local/origin state and recent helper events
   help      show this help
 
 Examples:
@@ -69,6 +71,7 @@ Examples:
   section0-docs pull
   section0-docs status
   section0-docs push-test
+  section0-docs trace
   MESSAGE="Update concept notes" section0-docs commit
   section0-docs push
 
@@ -92,6 +95,39 @@ for part in sys.argv[1].split("."):
 print(cur if cur is not None else "")' "\$1"
 }
 
+now_utc() {
+  date -u +%Y-%m-%dT%H:%M:%SZ
+}
+
+run_id() {
+  if command -v uuidgen >/dev/null 2>&1; then
+    uuidgen | tr '[:upper:]' '[:lower:]'
+  else
+    date -u +%Y%m%d%H%M%S
+  fi
+}
+
+json_log() {
+  need_python
+  mkdir -p "\$SESSION_DIR"
+  event="\$1"
+  detail="\${2:-}"
+  current_head="\$(git -C "\$REPO_DIR" rev-parse --short HEAD 2>/dev/null || true)"
+  current_branch="\$(git -C "\$REPO_DIR" branch --show-current 2>/dev/null || true)"
+  remote="\$(git -C "\$REPO_DIR" remote get-url origin 2>/dev/null || true)"
+  python3 -c 'import json,sys
+print(json.dumps({
+  "ts": sys.argv[1],
+  "event": sys.argv[2],
+  "detail": sys.argv[3],
+  "repo": sys.argv[4],
+  "branch": sys.argv[5],
+  "head": sys.argv[6],
+  "remote": sys.argv[7],
+}, separators=(",", ":")))' "\$(now_utc)" "\$event" "\$detail" "\$REPO_DIR" "\$current_branch" "\$current_head" "\$remote" >> "\$EVENTS_PATH"
+  chmod 600 "\$EVENTS_PATH"
+}
+
 open_url() {
   if command -v open >/dev/null 2>&1; then
     open "\$1" >/dev/null 2>&1 || true
@@ -132,6 +168,8 @@ install_git_credential() {
 auth_login() {
   need_python
   mkdir -p "\$SESSION_DIR"
+  login_run_id="\$(run_id)"
+  json_log "auth.login.start" "\$login_run_id"
   device_json="\$(curl -fsS -X POST "\$SERVER_URL/device")"
   code="\$(printf "%s" "\$device_json" | json_get code)"
   auth_url="\$(printf "%s" "\$device_json" | json_get authUrl)"
@@ -143,6 +181,8 @@ auth_login() {
   echo "  \$auth_url"
   echo "Device code:"
   echo "  \$code"
+  echo "Run id:"
+  echo "  \$login_run_id"
   echo "Token check:"
   echo "  \$SERVER_URL/device/\$code/token"
   open_url "\$auth_url"
@@ -238,6 +278,7 @@ print(json.dumps({
   echo "Git remote:    \$remote"
   echo "Git user:      \$git_username"
   echo "Session:       \$SESSION_PATH"
+  json_log "auth.login.complete" "\$author_email"
 }
 
 case "\${1:-help}" in
@@ -310,17 +351,44 @@ case "\${1:-help}" in
     ;;
   commit)
     : "\${MESSAGE:?Set MESSAGE before running commit}"
+    json_log "commit.start" "\$MESSAGE"
     git -C "\$REPO_DIR" add .
     git -C "\$REPO_DIR" commit -m "\$MESSAGE"
+    json_log "commit.complete" "\$(git -C "\$REPO_DIR" rev-parse --short HEAD)"
     ;;
   push)
+    before="\$(git -C "\$REPO_DIR" rev-parse --short HEAD)"
+    json_log "push.start" "\$before"
     git -C "\$REPO_DIR" push
+    git -C "\$REPO_DIR" fetch origin >/dev/null 2>&1 || true
+    origin_head="\$(git -C "\$REPO_DIR" rev-parse --short origin/main 2>/dev/null || true)"
+    json_log "push.complete" "\${origin_head:-\$before}"
+    echo "Pushed commit: \${origin_head:-\$before}"
+    echo "AFFiNE updates after the operator refresh runs."
     ;;
   push-test)
     branch="section0-smoke-\${USER:-user}-\$(date +%Y%m%d%H%M%S)"
     git -C "\$REPO_DIR" push origin HEAD:refs/heads/"\$branch"
     git -C "\$REPO_DIR" push origin :refs/heads/"\$branch"
     echo "Write access: ok"
+    json_log "push-test.complete" "\$branch"
+    ;;
+  trace)
+    echo "Repo: \$REPO_DIR"
+    echo "Remote: \$(git -C "\$REPO_DIR" remote get-url origin)"
+    echo "Branch: \$(git -C "\$REPO_DIR" branch --show-current)"
+    echo "Local HEAD: \$(git -C "\$REPO_DIR" rev-parse --short HEAD)"
+    git -C "\$REPO_DIR" fetch origin >/dev/null 2>&1 || true
+    echo "Origin HEAD: \$(git -C "\$REPO_DIR" rev-parse --short origin/main 2>/dev/null || true)"
+    echo "Status:"
+    git -C "\$REPO_DIR" status --short --branch
+    echo
+    echo "Recent helper events: \$EVENTS_PATH"
+    if [ -f "\$EVENTS_PATH" ]; then
+      tail -20 "\$EVENTS_PATH"
+    else
+      echo "no events yet"
+    fi
     ;;
   help|--help|-h)
     usage