mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-07 05:56:41 +02:00
feat(gbrain-sync): init, restore, uninstall, consumer registry
bin/gstack-brain-init: idempotent first-run. git init ~/.gstack/, .gitignore=*, canonical .brain-allowlist + .brain-privacy-map.json, pre-commit secret-scan hook (defense-in-depth), merge driver registration via git config, gh repo create --private OR arbitrary --remote <url>, initial push, ~/.gstack-brain-remote.txt for new-machine discovery, GBrain consumer registration via HTTP POST. bin/gstack-brain-restore: safe new-machine bootstrap. Refuses clobber of existing allowlisted files, clones to staging, rsync-copies tracked files, re-registers merge drivers (required — not cloned from remote), rehydrates consumers.json, prompts for per-consumer tokens. bin/gstack-brain-uninstall: clean off-ramp. Removes .git + .brain-* files + consumers.json + config keys. Preserves user data (learnings, plans, retros, profile). Optional --delete-remote for GitHub repos. bin/gstack-brain-consumer + bin/gstack-brain-reader (symlink alias): registry management. Internal 'consumer' term; user-facing 'reader' per DX review decision.
This commit is contained in:
Garry Tan
Executable
+360
@@ -0,0 +1,360 @@
|
||||
#!/usr/bin/env bash
|
||||
# gstack-brain-init — set up ~/.gstack/ as a git repo that syncs to GBrain.
|
||||
#
|
||||
# Usage:
|
||||
# gstack-brain-init [--remote <url>]
|
||||
#
|
||||
# Interactive by default. Pass --remote to skip the remote prompt.
|
||||
#
|
||||
# Idempotent: safe to re-run. If ~/.gstack/.git already exists AND points at
|
||||
# the same remote, reconfigures drivers/hooks/attributes without clobbering
|
||||
# history. If it points at a DIFFERENT remote, refuses and suggests
|
||||
# `gstack-brain-uninstall` first.
|
||||
#
|
||||
# What it does:
|
||||
# 1. git init ~/.gstack/ (or verify existing repo points at the right remote)
|
||||
# 2. Write .gitignore = "*" (ignore everything; allowlist is explicit)
|
||||
# 3. Write .brain-allowlist (canonical paths to sync)
|
||||
# 4. Write .brain-privacy-map.json (paths → privacy class)
|
||||
# 5. Write .gitattributes (register JSONL + union merge drivers)
|
||||
# 6. git config merge.jsonl-append.driver + merge.union.driver
|
||||
# 7. Install .git/hooks/pre-commit (defense-in-depth secret scan)
|
||||
# 8. Prompt for remote (default: gh repo create --private gstack-brain-$USER)
|
||||
# 9. Initial commit + push
|
||||
# 10. Write ~/.gstack-brain-remote.txt (URL-only, safe to share)
|
||||
# 11. Register GBrain consumer (HTTP POST if GBRAIN_URL set; else defer)
|
||||
#
|
||||
# Env:
|
||||
# GSTACK_HOME — override ~/.gstack
|
||||
# GBRAIN_URL — GBrain ingest endpoint base URL (for consumer registration)
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
CONFIG_BIN="$SCRIPT_DIR/gstack-config"
|
||||
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
|
||||
CONSUMERS_FILE="$GSTACK_HOME/consumers.json"
|
||||
|
||||
REMOTE_URL=""
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--remote) REMOTE_URL="$2"; shift 2 ;;
|
||||
--help|-h) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
|
||||
*) echo "Unknown flag: $1" >&2; exit 1 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
# ---- preconditions ----
|
||||
mkdir -p "$GSTACK_HOME"
|
||||
|
||||
EXISTING_REMOTE=""
|
||||
if [ -d "$GSTACK_HOME/.git" ]; then
|
||||
EXISTING_REMOTE=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
|
||||
if [ -n "$EXISTING_REMOTE" ] && [ -n "$REMOTE_URL" ] && [ "$EXISTING_REMOTE" != "$REMOTE_URL" ]; then
|
||||
cat >&2 <<EOF
|
||||
gstack-brain-init: ~/.gstack/ is already a git repo pointing at:
|
||||
$EXISTING_REMOTE
|
||||
|
||||
You asked to init with:
|
||||
$REMOTE_URL
|
||||
|
||||
Refusing to overwrite. To switch remotes, first run:
|
||||
gstack-brain-uninstall
|
||||
|
||||
(or edit the remote manually with: git -C ~/.gstack remote set-url origin <url>)
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# ---- choose the remote ----
|
||||
if [ -z "$REMOTE_URL" ] && [ -n "$EXISTING_REMOTE" ]; then
|
||||
REMOTE_URL="$EXISTING_REMOTE"
|
||||
echo "Using existing remote: $REMOTE_URL"
|
||||
fi
|
||||
|
||||
if [ -z "$REMOTE_URL" ]; then
|
||||
# Interactive prompt. Default: gh repo create (if available).
|
||||
echo "gstack-brain-init will create a private git repo that holds your"
|
||||
echo "gstack session memory across machines and lets GBrain index it."
|
||||
echo
|
||||
if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
|
||||
DEFAULT_NAME="gstack-brain-${USER:-$(whoami)}"
|
||||
echo "Default: gh will create a private repo named '$DEFAULT_NAME' under your account."
|
||||
printf "Press Enter to accept, or paste a custom git URL: "
|
||||
read -r REPLY || REPLY=""
|
||||
if [ -z "$REPLY" ]; then
|
||||
echo "Creating GitHub repo: $DEFAULT_NAME ..."
|
||||
if ! gh repo create "$DEFAULT_NAME" --private --description "gstack session memory" --source "$GSTACK_HOME" 2>/dev/null; then
|
||||
# Maybe the repo already exists; try to fetch its URL.
|
||||
REMOTE_URL=$(gh repo view "$DEFAULT_NAME" --json sshUrl -q .sshUrl 2>/dev/null || echo "")
|
||||
if [ -z "$REMOTE_URL" ]; then
|
||||
echo "Failed to create or find '$DEFAULT_NAME'. Try --remote <url>." >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "Repo already exists; using $REMOTE_URL"
|
||||
else
|
||||
REMOTE_URL=$(gh repo view "$DEFAULT_NAME" --json sshUrl -q .sshUrl 2>/dev/null || echo "")
|
||||
fi
|
||||
else
|
||||
REMOTE_URL="$REPLY"
|
||||
fi
|
||||
else
|
||||
echo "(gh CLI not found or not authenticated; provide a git URL directly)"
|
||||
printf "Paste a private git URL (e.g. git@github.com:you/gstack-brain.git): "
|
||||
read -r REMOTE_URL || REMOTE_URL=""
|
||||
if [ -z "$REMOTE_URL" ]; then
|
||||
echo "No URL provided. Aborting." >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# ---- verify remote reachable ----
|
||||
echo "Verifying remote connectivity: $REMOTE_URL"
|
||||
if ! git ls-remote "$REMOTE_URL" >/dev/null 2>&1; then
|
||||
cat >&2 <<EOF
|
||||
Remote not reachable: $REMOTE_URL
|
||||
This could mean:
|
||||
- Wrong URL
|
||||
- Not authenticated (GitHub: gh auth status; GitLab: glab auth status)
|
||||
- Network issue
|
||||
Fix and re-run gstack-brain-init.
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# ---- git init ----
|
||||
if [ ! -d "$GSTACK_HOME/.git" ]; then
|
||||
git -C "$GSTACK_HOME" init -q -b main 2>/dev/null || git -C "$GSTACK_HOME" init -q
|
||||
# If -b main wasn't supported, rename.
|
||||
git -C "$GSTACK_HOME" branch -M main 2>/dev/null || true
|
||||
fi
|
||||
|
||||
if [ -z "$(git -C "$GSTACK_HOME" remote 2>/dev/null)" ]; then
|
||||
git -C "$GSTACK_HOME" remote add origin "$REMOTE_URL"
|
||||
else
|
||||
git -C "$GSTACK_HOME" remote set-url origin "$REMOTE_URL"
|
||||
fi
|
||||
|
||||
# ---- write canonical files (idempotent) ----
|
||||
cat > "$GSTACK_HOME/.gitignore" <<'EOF'
|
||||
# gstack-brain sync: ignore-everything base. Paths are included explicitly via
|
||||
# .brain-allowlist and `git add -f` from gstack-brain-sync. Do not edit.
|
||||
*
|
||||
EOF
|
||||
|
||||
cat > "$GSTACK_HOME/.brain-allowlist" <<'EOF'
|
||||
# Canonical allowlist of paths that gstack-brain-sync will publish.
|
||||
# One glob per line. Anything not matching stays local.
|
||||
# Do not edit directly; managed by gstack-brain-init. User additions go below
|
||||
# the marker and survive re-init.
|
||||
projects/*/learnings.jsonl
|
||||
projects/*/*-reviews.jsonl
|
||||
projects/*/ceo-plans/*.md
|
||||
projects/*/ceo-plans/*/*.md
|
||||
projects/*/designs/*.md
|
||||
projects/*/designs/*/*.md
|
||||
projects/*/timeline.jsonl
|
||||
retros/*.md
|
||||
developer-profile.json
|
||||
builder-journey.md
|
||||
builder-profile.jsonl
|
||||
# NOT synced (per Codex v2 review — machine-local UX state):
|
||||
# projects/*/question-preferences.json (per-machine UX preferences)
|
||||
# projects/*/question-log.jsonl (audit/derivation log stays with preferences)
|
||||
# projects/*/question-events.jsonl (same)
|
||||
# ---- USER ADDITIONS BELOW ---- (survives re-init; above is managed)
|
||||
EOF
|
||||
|
||||
cat > "$GSTACK_HOME/.brain-privacy-map.json" <<'EOF'
|
||||
[
|
||||
{"pattern": "projects/*/learnings.jsonl", "class": "artifact"},
|
||||
{"pattern": "projects/*/*-reviews.jsonl", "class": "artifact"},
|
||||
{"pattern": "projects/*/ceo-plans/*.md", "class": "artifact"},
|
||||
{"pattern": "projects/*/ceo-plans/*/*.md", "class": "artifact"},
|
||||
{"pattern": "projects/*/designs/*.md", "class": "artifact"},
|
||||
{"pattern": "projects/*/designs/*/*.md", "class": "artifact"},
|
||||
{"pattern": "retros/*.md", "class": "artifact"},
|
||||
{"pattern": "builder-journey.md", "class": "artifact"},
|
||||
{"pattern": "projects/*/timeline.jsonl", "class": "behavioral"},
|
||||
{"pattern": "developer-profile.json", "class": "behavioral"},
|
||||
{"pattern": "builder-profile.jsonl", "class": "behavioral"}
|
||||
]
|
||||
EOF
|
||||
|
||||
cat > "$GSTACK_HOME/.gitattributes" <<'EOF'
|
||||
# gstack-brain: merge drivers for cross-machine sync conflicts.
|
||||
# Matching driver must be registered in local git config; gstack-brain-init
|
||||
# and gstack-brain-restore run `git config merge.<name>.driver ...` after init.
|
||||
*.jsonl merge=jsonl-append
|
||||
retros/*.md merge=union
|
||||
projects/*/designs/**/*.md merge=union
|
||||
projects/*/ceo-plans/**/*.md merge=union
|
||||
EOF
|
||||
|
||||
# ---- register merge drivers in local git config ----
|
||||
git -C "$GSTACK_HOME" config merge.jsonl-append.driver "$SCRIPT_DIR/gstack-jsonl-merge %O %A %B"
|
||||
git -C "$GSTACK_HOME" config merge.jsonl-append.name "gstack JSONL append-only merger"
|
||||
git -C "$GSTACK_HOME" config merge.union.driver "cat %A %B > %A.merged && mv %A.merged %A"
|
||||
git -C "$GSTACK_HOME" config merge.union.name "union concat"
|
||||
|
||||
# ---- install pre-commit hook (defense-in-depth) ----
|
||||
HOOK="$GSTACK_HOME/.git/hooks/pre-commit"
|
||||
mkdir -p "$(dirname "$HOOK")"
|
||||
cat > "$HOOK" <<'HOOK_EOF'
|
||||
#!/usr/bin/env bash
|
||||
# gstack-brain pre-commit hook — secret-scan defense-in-depth.
|
||||
# The primary scanner runs inside gstack-brain-sync BEFORE staging. This hook
|
||||
# catches any manual `git commit` a user might accidentally run against the
|
||||
# brain repo.
|
||||
set -uo pipefail
|
||||
|
||||
python3 -c "
|
||||
import sys, re, subprocess
|
||||
try:
|
||||
out = subprocess.check_output(['git', 'diff', '--cached'], stderr=subprocess.DEVNULL).decode('utf-8', 'replace')
|
||||
except Exception:
|
||||
sys.exit(0)
|
||||
|
||||
patterns = [
|
||||
('aws-access-key', re.compile(r'AKIA[0-9A-Z]{16}')),
|
||||
('github-token', re.compile(r'\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})')),
|
||||
('openai-key', re.compile(r'\bsk-[A-Za-z0-9_-]{20,}')),
|
||||
('pem-block', re.compile(r'-----BEGIN [A-Z ]{3,}-----')),
|
||||
('jwt', re.compile(r'\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b')),
|
||||
('bearer-token-json',
|
||||
re.compile(r'\"(authorization|api[_-]?key|apikey|token|secret|password)\"\s*:\s*\"[A-Za-z0-9_./+=-]{16,}\"',
|
||||
re.IGNORECASE)),
|
||||
]
|
||||
for name, rx in patterns:
|
||||
if rx.search(out):
|
||||
sys.stderr.write(f'gstack-brain pre-commit: refusing commit — {name} detected in staged diff.\n')
|
||||
sys.stderr.write('Either edit the offending file, or if intentional, run:\n')
|
||||
sys.stderr.write(' gstack-brain-sync --skip-file <path> (to permanently exclude)\n')
|
||||
sys.exit(1)
|
||||
sys.exit(0)
|
||||
"
|
||||
HOOK_EOF
|
||||
chmod +x "$HOOK"
|
||||
|
||||
# ---- initial commit (idempotent; skips if already committed) ----
|
||||
cd "$GSTACK_HOME"
|
||||
git add -f .gitignore .brain-allowlist .brain-privacy-map.json .gitattributes
|
||||
# Only commit if the index has changes from HEAD (if there is a HEAD).
|
||||
if git rev-parse HEAD >/dev/null 2>&1; then
|
||||
if ! git diff --cached --quiet 2>/dev/null; then
|
||||
git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
|
||||
commit -q -m "chore: gstack-brain-init (refresh sync config)"
|
||||
fi
|
||||
else
|
||||
# First commit ever.
|
||||
git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
|
||||
commit -q -m "chore: gstack-brain-init"
|
||||
fi
|
||||
|
||||
# ---- initial push ----
|
||||
if ! git push -q -u origin main 2>/dev/null; then
|
||||
# Maybe the default branch is master, or the remote has existing content.
|
||||
# Try to resolve: fetch + fast-forward merge + push.
|
||||
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
|
||||
if git fetch origin 2>/dev/null && git pull --ff-only origin "$CURRENT_BRANCH" 2>/dev/null; then
|
||||
git push -q -u origin "$CURRENT_BRANCH" || {
|
||||
echo "Push to $REMOTE_URL failed. The remote may have divergent content." >&2
|
||||
echo "Try: cd ~/.gstack && git pull --rebase origin $CURRENT_BRANCH && git push origin $CURRENT_BRANCH" >&2
|
||||
exit 1
|
||||
}
|
||||
else
|
||||
# Couldn't fetch/merge; print what to do.
|
||||
echo "Push to $REMOTE_URL failed and fetch/merge didn't help." >&2
|
||||
echo "Manual recovery: cd ~/.gstack && git status, then push once conflicts are resolved." >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# ---- write the remote-url helper file (outside ~/.gstack/, survives restore) ----
|
||||
echo "$REMOTE_URL" > "$REMOTE_FILE"
|
||||
chmod 600 "$REMOTE_FILE"
|
||||
|
||||
# ---- register GBrain consumer ----
|
||||
mkdir -p "$GSTACK_HOME"
|
||||
CONSUMER_STATUS="pending"
|
||||
GBRAIN_URL_VAL="${GBRAIN_URL:-$("$CONFIG_BIN" get gbrain_url 2>/dev/null || echo "")}"
|
||||
GBRAIN_TOKEN_VAL="${GBRAIN_TOKEN:-$("$CONFIG_BIN" get gbrain_token 2>/dev/null || echo "")}"
|
||||
|
||||
if [ -n "$GBRAIN_URL_VAL" ] && [ -n "$GBRAIN_TOKEN_VAL" ]; then
|
||||
# Try the HTTP handoff.
|
||||
HTTP_RESP=$(curl -sS -X POST "${GBRAIN_URL_VAL%/}/ingest-repo" \
|
||||
-H "Authorization: Bearer $GBRAIN_TOKEN_VAL" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data "{\"repo_url\":\"$REMOTE_URL\"}" \
|
||||
-w "\n%{http_code}" 2>&1 || echo -e "\ncurl-error")
|
||||
HTTP_CODE=$(echo "$HTTP_RESP" | tail -1)
|
||||
if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "204" ]; then
|
||||
CONSUMER_STATUS="ok"
|
||||
echo "GBrain consumer registered: $GBRAIN_URL_VAL"
|
||||
else
|
||||
echo "GBrain ingest endpoint returned HTTP $HTTP_CODE; will retry on next skill run."
|
||||
fi
|
||||
elif [ -z "$GBRAIN_URL_VAL" ]; then
|
||||
echo "(GBRAIN_URL not configured; skipping consumer registration. Set it with:"
|
||||
echo " gstack-config set gbrain_url <url>"
|
||||
echo " gstack-config set gbrain_token <token>"
|
||||
echo " then run: gstack-brain-consumer add gbrain --ingest-url <url> --token <token>)"
|
||||
fi
|
||||
|
||||
# Write consumers.json — the canonical registry. Tokens are NOT stored here;
|
||||
# they stay in gstack-config (machine-local). This file IS synced so a new
|
||||
# machine knows which consumers exist and can prompt for tokens.
|
||||
python3 - "$CONSUMERS_FILE" "$GBRAIN_URL_VAL" "$CONSUMER_STATUS" <<'PYEOF'
|
||||
import sys, json, os
|
||||
path, url, status = sys.argv[1:4]
|
||||
try:
|
||||
with open(path) as f:
|
||||
data = json.load(f)
|
||||
except (FileNotFoundError, json.JSONDecodeError):
|
||||
data = {"consumers": []}
|
||||
# Upsert GBrain entry.
|
||||
entry = {"name": "gbrain", "ingest_url": url, "status": status, "token_ref": "gbrain_token"}
|
||||
updated = False
|
||||
for i, c in enumerate(data.get("consumers", [])):
|
||||
if c.get("name") == "gbrain":
|
||||
data["consumers"][i] = entry
|
||||
updated = True
|
||||
break
|
||||
if not updated:
|
||||
data.setdefault("consumers", []).append(entry)
|
||||
with open(path, "w") as f:
|
||||
json.dump(data, f, indent=2)
|
||||
f.write("\n")
|
||||
PYEOF
|
||||
|
||||
# Stage and commit consumers.json in the same session.
|
||||
cd "$GSTACK_HOME"
|
||||
git add -f consumers.json 2>/dev/null || true
|
||||
if ! git diff --cached --quiet 2>/dev/null; then
|
||||
git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
|
||||
commit -q -m "chore: register GBrain consumer"
|
||||
git push -q origin HEAD 2>/dev/null || true
|
||||
fi
|
||||
|
||||
# ---- done ----
|
||||
cat <<EOF
|
||||
|
||||
gstack-brain-init complete.
|
||||
Repo: $GSTACK_HOME (git)
|
||||
Remote: $REMOTE_URL
|
||||
Remote URL also saved at: $REMOTE_FILE
|
||||
|
||||
Sync happens automatically at the start and end of each skill (no daemon).
|
||||
Check status anytime with:
|
||||
gstack-brain-sync --status
|
||||
|
||||
To activate sync, the next skill you run will ask you one question about
|
||||
privacy mode (sync everything / artifacts only / off).
|
||||
|
||||
New machine? On the other laptop, put a copy of:
|
||||
$REMOTE_FILE
|
||||
in that machine's home directory, then run: gstack-brain-restore
|
||||
EOF
|
||||
Reference in New Issue
Block a user