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
2026-04-22 13:47:11 -07:00
parent 97cbacf409
commit f088fe96f8
5 changed files with 937 additions and 0 deletions
+196
View File
@@ -0,0 +1,196 @@
#!/usr/bin/env bash
# gstack-brain-consumer — manage the consumer (reader) registry.
#
# Consumer = a reader that ingests the gstack-brain git repo as a source of
# session memory. v1 primary consumer is GBrain; later versions can register
# Codex, OpenClaw, or third-party readers.
#
# NOTE ON NAMING: internally this helper uses "consumer" (correct data-model
# term). User-facing copy and the alias `gstack-brain-reader` use "reader"
# (matches user mental model: "what's reading my brain?").
#
# Usage:
# gstack-brain-consumer add <name> --ingest-url <url> --token <token>
# gstack-brain-consumer list
# gstack-brain-consumer remove <name>
# gstack-brain-consumer test <name>
#
# Env:
# GSTACK_HOME — override ~/.gstack
set -euo pipefail
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
CONSUMERS_FILE="$GSTACK_HOME/consumers.json"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CONFIG_BIN="$SCRIPT_DIR/gstack-config"
ensure_file() {
mkdir -p "$GSTACK_HOME"
if [ ! -f "$CONSUMERS_FILE" ]; then
echo '{"consumers": []}' > "$CONSUMERS_FILE"
fi
}
get_remote_url() {
git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo ""
}
sub_add() {
local name="" url="" token=""
local positional=""
while [ $# -gt 0 ]; do
case "$1" in
--ingest-url) url="$2"; shift 2 ;;
--token) token="$2"; shift 2 ;;
--) shift; break ;;
-*) echo "Unknown flag: $1" >&2; exit 1 ;;
*) positional="$1"; shift ;;
esac
done
name="$positional"
if [ -z "$name" ] || [ -z "$url" ]; then
echo "Usage: gstack-brain-consumer add <name> --ingest-url <url> [--token <token>]" >&2
exit 1
fi
ensure_file
# Upsert in consumers.json, store token in gstack-config under `<name>_token`.
python3 - "$CONSUMERS_FILE" "$name" "$url" <<'PYEOF'
import sys, json
path, name, url = sys.argv[1:4]
try:
with open(path) as f:
data = json.load(f)
except Exception:
data = {"consumers": []}
entry = {"name": name, "ingest_url": url, "status": "unknown", "token_ref": f"{name}_token"}
cs = data.setdefault("consumers", [])
for i, c in enumerate(cs):
if c.get("name") == name:
cs[i] = entry
break
else:
cs.append(entry)
with open(path, "w") as f:
json.dump(data, f, indent=2)
f.write("\n")
print(f"registered consumer: {name}")
PYEOF
if [ -n "$token" ]; then
"$CONFIG_BIN" set "${name}_token" "$token"
echo "token stored: gstack-config get ${name}_token to retrieve"
fi
# Attempt registration with remote (HTTP POST).
sub_test "$name"
}
sub_list() {
if [ ! -f "$CONSUMERS_FILE" ]; then
echo '{"consumers": []}'
return 0
fi
cat "$CONSUMERS_FILE"
}
sub_remove() {
local name="${1:-}"
if [ -z "$name" ]; then
echo "Usage: gstack-brain-consumer remove <name>" >&2
exit 1
fi
ensure_file
python3 - "$CONSUMERS_FILE" "$name" <<'PYEOF'
import sys, json
path, name = sys.argv[1:3]
try:
with open(path) as f:
data = json.load(f)
except Exception:
data = {"consumers": []}
before = len(data.get("consumers", []))
data["consumers"] = [c for c in data.get("consumers", []) if c.get("name") != name]
after = len(data["consumers"])
with open(path, "w") as f:
json.dump(data, f, indent=2)
f.write("\n")
print(f"removed: {before - after} entry(ies)")
PYEOF
}
sub_test() {
local name="${1:-}"
if [ -z "$name" ]; then
echo "Usage: gstack-brain-consumer test <name>" >&2
exit 1
fi
ensure_file
# Look up the consumer by name.
local info
info=$(python3 - "$CONSUMERS_FILE" "$name" <<'PYEOF'
import sys, json
path, name = sys.argv[1:3]
try:
with open(path) as f:
data = json.load(f)
except Exception:
data = {"consumers": []}
for c in data.get("consumers", []):
if c.get("name") == name:
print(c.get("ingest_url", ""))
sys.exit(0)
sys.exit(1)
PYEOF
) || { echo "No such consumer: $name" >&2; exit 1; }
local url="$info"
local token
token=$("$CONFIG_BIN" get "${name}_token" 2>/dev/null || echo "")
if [ -z "$url" ] || [ -z "$token" ]; then
echo "consumer '$name': url or token missing; cannot test"
return 0
fi
local repo_url
repo_url=$(get_remote_url)
echo "Testing $name at ${url%/}/ingest-repo ..."
local resp
resp=$(curl -sS -X POST "${url%/}/ingest-repo" \
-H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
--data "{\"repo_url\":\"$repo_url\"}" \
-w "\n%{http_code}" 2>&1 || echo -e "\ncurl-error")
local code
code=$(echo "$resp" | tail -1)
if [ "$code" = "200" ] || [ "$code" = "201" ] || [ "$code" = "204" ]; then
echo "ok (HTTP $code)"
# Update status in consumers.json.
python3 - "$CONSUMERS_FILE" "$name" "ok" <<'PYEOF'
import sys, json
path, name, status = sys.argv[1:4]
with open(path) as f: data = json.load(f)
for c in data.get("consumers", []):
if c.get("name") == name:
c["status"] = status
with open(path, "w") as f: json.dump(data, f, indent=2); f.write("\n")
PYEOF
else
echo "failed (HTTP $code)"
python3 - "$CONSUMERS_FILE" "$name" "error" <<'PYEOF'
import sys, json
path, name, status = sys.argv[1:4]
with open(path) as f: data = json.load(f)
for c in data.get("consumers", []):
if c.get("name") == name:
c["status"] = status
with open(path, "w") as f: json.dump(data, f, indent=2); f.write("\n")
PYEOF
fi
}
case "${1:-}" in
add) shift; sub_add "$@" ;;
list) sub_list ;;
remove) shift; sub_remove "$@" ;;
test) shift; sub_test "$@" ;;
--help|-h|"") sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//' ;;
*) echo "Unknown subcommand: $1" >&2; exit 1 ;;
esac
+360
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
gstack-brain-consumer
+235
View File
@@ -0,0 +1,235 @@
#!/usr/bin/env bash
# gstack-brain-restore — bootstrap a new machine from an existing brain repo.
#
# Usage:
# gstack-brain-restore [<git-remote-url>]
#
# If no URL is given, reads from ~/.gstack-brain-remote.txt (written by
# gstack-brain-init on the original machine). Copy that file to the new
# machine before running this command.
#
# Safety gates (refuses with clear message):
# - ~/.gstack/.git already exists with a DIFFERENT remote
# - ~/.gstack/ contains non-allowlisted, non-gitignored user files
# that would be clobbered by restore
#
# What it does:
# 1. Clone the remote to a staging directory
# 2. Validate the repo is gstack-brain-shaped (.brain-allowlist, .gitattributes)
# 3. rsync-copy tracked files into ~/.gstack/ with skip-if-same-hash
# 4. Move staging's .git into ~/.gstack/.git
# 5. Register local git config merge drivers (they don't clone from remote)
# 6. Rehydrate consumers.json endpoints; prompt for tokens
#
# Env:
# GSTACK_HOME — override ~/.gstack
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"
REMOTE_URL="${1:-}"
if [ -z "$REMOTE_URL" ]; then
if [ -f "$REMOTE_FILE" ]; then
REMOTE_URL=$(head -1 "$REMOTE_FILE" | tr -d '[:space:]')
fi
fi
if [ -z "$REMOTE_URL" ]; then
cat >&2 <<EOF
gstack-brain-restore: no remote URL provided.
Provide one of:
gstack-brain-restore <git-url>
or put the URL in $REMOTE_FILE (copy from the original machine)
EOF
exit 1
fi
# ---- safety gates ----
if [ -d "$GSTACK_HOME/.git" ]; then
EXISTING_REMOTE=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
if [ -n "$EXISTING_REMOTE" ] && [ "$EXISTING_REMOTE" != "$REMOTE_URL" ]; then
cat >&2 <<EOF
gstack-brain-restore: ~/.gstack/.git already points at:
$EXISTING_REMOTE
You asked to restore from:
$REMOTE_URL
Refusing to overwrite. Run 'gstack-brain-uninstall' first or pass a matching URL.
EOF
exit 1
fi
fi
# ---- clone to staging ----
STAGING=$(mktemp -d "${TMPDIR:-/tmp}/gstack-brain-restore.XXXXXX")
trap 'rm -rf "$STAGING" 2>/dev/null' EXIT
echo "Cloning $REMOTE_URL to staging..."
if ! git clone --quiet "$REMOTE_URL" "$STAGING/repo" 2>/dev/null; then
echo "Clone failed. Check:" >&2
echo " - URL is correct: $REMOTE_URL" >&2
echo " - Auth: gh auth status (github) / glab auth status (gitlab)" >&2
exit 1
fi
# ---- validate shape ----
if [ ! -f "$STAGING/repo/.brain-allowlist" ] || [ ! -f "$STAGING/repo/.gitattributes" ]; then
cat >&2 <<EOF
gstack-brain-restore: $REMOTE_URL does not look like a gstack-brain repo.
Missing: .brain-allowlist and/or .gitattributes
This command only works on repos created by gstack-brain-init.
EOF
exit 1
fi
# ---- validate target ~/.gstack/ has no non-gitignored user files ----
mkdir -p "$GSTACK_HOME"
if [ ! -d "$GSTACK_HOME/.git" ]; then
# No existing git → check if we'd clobber anything allowlisted.
# Read the new allowlist globs and see if any existing files would collide.
CLOBBER_RISK=$(python3 - "$GSTACK_HOME" "$STAGING/repo/.brain-allowlist" <<'PYEOF'
import sys, os, fnmatch
home, allowlist_path = sys.argv[1:3]
try:
with open(allowlist_path) as f:
globs = [l.strip() for l in f if l.strip() and not l.lstrip().startswith('#')]
except FileNotFoundError:
globs = []
risks = []
for root, dirs, files in os.walk(home):
dirs[:] = [d for d in dirs if d != '.git']
for name in files:
full = os.path.join(root, name)
rel = os.path.relpath(full, home)
for g in globs:
if fnmatch.fnmatchcase(rel, g):
risks.append(rel)
break
for r in risks[:5]:
print(r)
if len(risks) > 5:
print(f"...and {len(risks) - 5} more")
sys.exit(0 if not risks else 2)
PYEOF
) || true
if [ -n "$CLOBBER_RISK" ]; then
cat >&2 <<EOF
gstack-brain-restore: ~/.gstack/ has existing allowlisted files that would
be clobbered by restore:
$CLOBBER_RISK
Back these up first, or run this command on a machine with an empty
~/.gstack/. If these files are from an earlier gstack session on THIS
machine, you probably want to run gstack-brain-init instead (to create a
new brain repo with this machine's state).
EOF
exit 1
fi
fi
# ---- copy tracked files in ----
echo "Copying tracked files into ~/.gstack/ ..."
# Use git-ls-tree to get exact tracked file list (avoids staged/untracked files).
cd "$STAGING/repo"
git ls-tree -r --name-only HEAD | while IFS= read -r rel_path; do
src="$STAGING/repo/$rel_path"
dst="$GSTACK_HOME/$rel_path"
mkdir -p "$(dirname "$dst")"
# Skip if identical (content hash). Otherwise copy.
if [ -f "$dst" ] && cmp -s "$src" "$dst"; then
continue
fi
cp "$src" "$dst"
done
# ---- move .git into place ----
if [ -d "$GSTACK_HOME/.git" ]; then
# Existing .git with matching remote — just fetch + fast-forward.
git -C "$GSTACK_HOME" fetch origin >/dev/null 2>&1 || true
else
mv "$STAGING/repo/.git" "$GSTACK_HOME/.git"
fi
# ---- register merge drivers (local git config; don't survive clones) ----
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 (same as init) ----
HOOK="$GSTACK_HOME/.git/hooks/pre-commit"
mkdir -p "$(dirname "$HOOK")"
cat > "$HOOK" <<'HOOK_EOF'
#!/usr/bin/env bash
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.\n')
sys.exit(1)
sys.exit(0)
"
HOOK_EOF
chmod +x "$HOOK"
# ---- rehydrate consumers, prompt for tokens ----
if [ -f "$GSTACK_HOME/consumers.json" ]; then
echo ""
echo "Consumer registry restored. Tokens are machine-local and NOT synced."
echo "Run these for each consumer to re-enter tokens:"
python3 - "$GSTACK_HOME/consumers.json" <<'PYEOF'
import sys, json
try:
with open(sys.argv[1]) as f:
data = json.load(f)
except Exception:
sys.exit(0)
for c in data.get("consumers", []):
name = c.get("name", "")
token_ref = c.get("token_ref", f"{name}_token")
print(f" gstack-config set {token_ref} <your-token>")
PYEOF
fi
# ---- write remote helper file if missing ----
if [ ! -f "$REMOTE_FILE" ]; then
echo "$REMOTE_URL" > "$REMOTE_FILE"
chmod 600 "$REMOTE_FILE"
echo ""
echo "Wrote $REMOTE_FILE for future skill-run auto-detection."
fi
cat <<EOF
gstack-brain-restore complete.
Local: $GSTACK_HOME
Remote: $REMOTE_URL
Next skill run will ask about privacy mode (one-time question) and then
sync automatically at skill boundaries.
Status anytime: gstack-brain-sync --status
EOF
+145
View File
@@ -0,0 +1,145 @@
#!/usr/bin/env bash
# gstack-brain-uninstall — clean off-ramp for gstack-brain sync.
#
# Usage:
# gstack-brain-uninstall [--yes] [--delete-remote]
#
# Removes the git layer from ~/.gstack/ and clears sync config. Your local
# gstack memory (learnings, timelines, etc.) is NOT touched — this is an
# uninstall-sync command, not a delete-data command.
#
# Flags:
# --yes Skip the confirmation prompt.
# --delete-remote Also delete the GitHub repo via `gh repo delete`
# (interactive unless --yes is also passed).
#
# What it removes (in ~/.gstack/):
# .git/ — the sync repo's git data
# .gitignore — canonical ignore-all marker
# .gitattributes — merge driver declarations
# .brain-allowlist — sync path list
# .brain-privacy-map.json — sync privacy classifier
# .brain-queue.jsonl — pending queue
# .brain-discover-cursor — discover-new cursor
# .brain-last-push — timestamp marker
# .brain-skip.txt — user-maintained skip list
# .brain-sync.lock.d/ — lock dir (if present)
# .brain-sync-status.json — health status
# consumers.json — consumer/reader registry
#
# What it clears (via gstack-config):
# gbrain_sync_mode → off
# gbrain_sync_mode_prompted → false (so user re-prompts on re-init)
#
# What it does NOT touch:
# Project data (projects/*, retros/*, developer-profile.json, etc.)
# Consumer tokens in gstack-config (<name>_token keys)
# ~/.gstack-brain-remote.txt in your home directory
# The actual remote git repo (unless --delete-remote)
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"
ASSUME_YES=0
DELETE_REMOTE=0
while [ $# -gt 0 ]; do
case "$1" in
--yes|-y) ASSUME_YES=1; shift ;;
--delete-remote) DELETE_REMOTE=1; shift ;;
--help|-h) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
*) echo "Unknown flag: $1" >&2; exit 1 ;;
esac
done
if [ ! -d "$GSTACK_HOME/.git" ]; then
echo "gstack-brain-uninstall: nothing to do (~/.gstack/.git doesn't exist)."
exit 0
fi
REMOTE_URL=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
# ---- confirmation ----
if [ "$ASSUME_YES" != "1" ]; then
cat <<EOF
This will remove gstack-brain sync from this machine:
- Remove ~/.gstack/.git and sync config files
- Clear gbrain_sync_mode in gstack-config
- Remote: $REMOTE_URL will be $([ "$DELETE_REMOTE" = "1" ] && echo "DELETED" || echo "kept")
Local memory (learnings, plans, etc.) is NOT touched.
EOF
printf "Proceed? [y/N] "
read -r reply
case "$reply" in
y|Y|yes|Yes) ;;
*) echo "Aborted."; exit 0 ;;
esac
fi
# ---- delete remote if requested ----
if [ "$DELETE_REMOTE" = "1" ] && [ -n "$REMOTE_URL" ]; then
case "$REMOTE_URL" in
*github.com*|*@github*)
if command -v gh >/dev/null 2>&1; then
# Extract owner/repo from URL.
REPO_SLUG=$(echo "$REMOTE_URL" | sed -E 's#.*[:/]([^/:]+/[^/]+)(\.git)?$#\1#' | sed 's/\.git$//')
if [ -n "$REPO_SLUG" ]; then
echo "Deleting GitHub repo: $REPO_SLUG"
if [ "$ASSUME_YES" = "1" ]; then
gh repo delete "$REPO_SLUG" --yes 2>/dev/null || echo "gh repo delete failed; continuing local uninstall"
else
gh repo delete "$REPO_SLUG" 2>/dev/null || echo "gh repo delete failed; continuing local uninstall"
fi
fi
else
echo "--delete-remote requires the gh CLI. Skipping remote deletion."
fi
;;
*)
echo "--delete-remote only supports github.com remotes. Delete manually if needed: $REMOTE_URL"
;;
esac
fi
# ---- remove sync files ----
echo "Removing git layer and sync config files..."
rm -rf "$GSTACK_HOME/.git" 2>/dev/null || true
rm -f "$GSTACK_HOME/.gitignore" 2>/dev/null || true
rm -f "$GSTACK_HOME/.gitattributes" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-allowlist" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-privacy-map.json" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-queue.jsonl" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-discover-cursor" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-last-push" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-last-pull" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-skip.txt" 2>/dev/null || true
rm -f "$GSTACK_HOME/.brain-sync-status.json" 2>/dev/null || true
rm -rf "$GSTACK_HOME/.brain-sync.lock.d" 2>/dev/null || true
rm -f "$GSTACK_HOME/consumers.json" 2>/dev/null || true
# ---- clear config keys ----
"$CONFIG_BIN" set gbrain_sync_mode off >/dev/null 2>&1 || true
"$CONFIG_BIN" set gbrain_sync_mode_prompted false >/dev/null 2>&1 || true
# ---- leave remote-helper file alone unless user asked to delete remote ----
if [ "$DELETE_REMOTE" = "1" ]; then
rm -f "$REMOTE_FILE" 2>/dev/null || true
else
if [ -f "$REMOTE_FILE" ]; then
echo "(keeping $REMOTE_FILE — remove manually if you want to forget the URL)"
fi
fi
cat <<EOF
gstack-brain uninstall complete.
Sync is off. ~/.gstack/ is a plain directory again.
Your project data, learnings, and profile are untouched.
To re-enable sync later: gstack-brain-init
EOF